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 tokenUpdate 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_IPbecomes
curl https://api.captchafox.com/siteverify \
-d secret=YOUR_SECRET \
-d response=TOKEN \
-d remoteIp=VISITOR_IP \
-d sitekey=YOUR_SITEKEYThe 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
- Submit the protected form.
- Check that your server receives the
cf-captcha-responsefield. - 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.