Docs
Tutorials
Migrate from reCAPTCHA

Migrate from reCAPTCHA

You can migrate from Google reCAPTCHA “fast” using compatibility mode for server-side and client-side parts or you can fully migrate to Private Captcha.

To proceed with migration, in Private Captcha portal you need to get a sitekey for client-side (property integrations) and API key for backend (account settings).

Fast migration

“Fast” migration makes it possible to migrate with absolutely minimal amount of changes to front-end or backend-end to use your existing integration code.

Client-side

Private Captcha offers a compatibility mode for the website integration: just add ?compat=recaptcha script parameters when you include Private Captcha script.

index.html
@@ -18,7 +18,13 @@
- <script src="https://www.google.com/recaptcha/api.js" async defer></script>
+ <script src="https://cdn.privatecaptcha.com/widget/js/privatecaptcha.js?compat=recaptcha" defer></script>

Compatibility mode means the following:

  • solution form field will be called g-recaptcha-response instead of private-captcha-solution
  • Private Captcha JavaScript object is available as grecaptcha global property
  • Private Captcha looks for elements with g-recaptcha class instead of private-captcha for automatic widget rendering
  • All compatible global APIs for reCAPTCHA like render() or getResponse() are also present

Note

Private Captcha offers invisible mode with execute() API too

Explicit rendering

By default, when you include the client script, Private Captcha initializes all elements that have g-recaptcha class attached (that is, in reCAPTCHA compatibility mode).

However, you can also explicitly render captcha elements using window.grecaptcha.render(htmlElement, options) API. To do so, add another argument to Javascript script include: render=explicit and then explicitly call render() for all elements that you need.

Server-side

Private Captcha offers reCAPTCHA compatible API endpoint /siteverify, that you can use like this:

- "https://www.google.com/recaptcha/api/siteverify"
+ "https://api.privatecaptcha.com/siteverify"

Warning

Google reCAPTCHA also supports GET request type to /siteverify endpoint (in addition to POST), but Private Captcha only supports POST

By default endpoint returns responses in reCAPTCHA v2 format. In case you are using reCAPTCHA v3, you need to add an additional header X-Captcha-Compat-Version: rcV3 to your requests and response will follow v3-compatible API.

Full migration

Note

Full migration is recommended as it is quite easy and it uses more efficient codepaths.

To migrate from reCAPTCHA completely, you need to rely on Private Captcha semantics on the client-side and use one of the pre-built integrations on the server side.

Client-side

Even without compatibility mode (above), Private Captcha offers a similar client-side API as reCAPTCHA, so migration shouldn’t cause a lot of pain.

Things you generally will need to do:

  • replace script src address to use the Private Captcha one
  • replace added class g-recaptcha to private-captcha for automatic/implicit rendering (the default)
  • replace usage of grecaptcha global object (if any) to privateCaptcha
  • change stub sitekeys for testing, if you have any

You can check full widget documentation for front-end details.

Server-side

Private Captcha offers a lot of pre-built integrations so your backend technology is very likely covered. If not, you can rely on OpenAPI spec to generate your client (or write one yourself, as it’s doing only a single POST request to an API endpoint).

Last updated on
Complete example