Skip to Content
Migrate to CaptchaFoxFrom reCAPTCHA

Migrate from reCAPTCHA

This guide covers reCAPTCHA v2, both the checkbox and the invisible variant. Most changes are renames.

Get your CaptchaFox keys

Create a site in the CaptchaFox portal and copy its sitekey and secret key. Your reCAPTCHA keys won’t work with CaptchaFox.

Update client-side code

Replace the script tag

<script src="https://www.google.com/recaptcha/api.js" async defer></script>

becomes

<script src="https://cdn.captchafox.com/api.js" async defer></script>

Query parameter hl becomes lang.

Update the container element

<div class="g-recaptcha" data-sitekey="RECAPTCHA_SITEKEY"></div>

becomes

<div class="captchafox" data-sitekey="YOUR_SITEKEY"></div>

Invisible reCAPTCHA: data-size="invisible" becomes data-mode="hidden". See Hidden Mode.

Update JavaScript API calls

Only if you use the JavaScript API:

const id = grecaptcha.render('container', { sitekey: 'RECAPTCHA_SITEKEY', callback: handleVerify, 'expired-callback': handleExpire, 'error-callback': handleError, }); grecaptcha.getResponse(id); grecaptcha.reset(id); grecaptcha.execute(id);

becomes

const id = captchafox.render('container', { sitekey: 'YOUR_SITEKEY', onVerify: handleVerify, onExpire: handleExpire, onError: handleError, }); captchafox.getResponse(id); captchafox.reset(id); const token = await captchafox.execute(id); // resolves with the token

Update server-side code

Read the token from the new form field and send it to the CaptchaFox endpoint, with the secret key of your CaptchaFox site:

curl https://www.google.com/recaptcha/api/siteverify \ -d secret=RECAPTCHA_SECRET \ -d response=TOKEN \ -d remoteip=VISITOR_IP

becomes

curl https://api.captchafox.com/siteverify \ -d secret=YOUR_SECRET \ -d response=TOKEN \ -d remoteIp=VISITOR_IP \ -d sitekey=YOUR_SITEKEY

The response fields stay the same: success, challenge_ts, hostname and error-codes. See Verify the Response.

Update your Content Security Policy

If your site uses a Content Security Policy, remove the reCAPTCHA sources (www.google.com, www.gstatic.com, www.recaptcha.net) and add the CaptchaFox sources.

Switch libraries

If you use a reCAPTCHA library for your frontend or backend, switch to one of our libraries. See all integrations  for the full list.

Test your migration

  1. Submit the protected form.
  2. Check that your server receives the cf-captcha-response field.
  3. Check that the verification request returns "success": true.

To test without a site, use the test keys. Replace them with your real keys before going live.

Last updated on