Skip to main content
Version: v2

Migrating from hCaptcha

Switching from hCaptcha to Friendly Captcha is straightforward.

To make the switch even easier we offer a hcaptcha compatibility mode. Using that compatibility mode switching should take only a few minutes.

Create a Friendly Captcha sitekey and API Key​

info

To add the Friendly Captcha widget to your website you will need an account. You can sign up here.

Log in to the Friendly Captcha Dashboard, then

  1. Create a new application and take note of its sitekey.
  2. Create a new API key and copy it somewhere safe.
tip

If you are using a CMS like WordPress, you probably don't have to do the below steps.

Instead you would replace the hCaptcha plugin and install a plugin that supports Friendly Captcha.

Update your website's integration​

  1. Replace the hCaptcha script

    <script src="https://js.hcaptcha.com/1/api.js"
            async defer></script>

    with the hCAPTCHA-compatible Friendly Captcha scripts.

    <script type="module" src="https://cdn.jsdelivr.net/npm/@friendlycaptcha/[email protected]/contrib/hcaptcha-site.min.js"
            async defer></script>
    <script nomodule src="https://cdn.jsdelivr.net/npm/@friendlycaptcha/[email protected]/contrib/hcaptcha-site.compat.min.js"
          async defer></script>
    info

    If you are making use of query parameters to configure hCaptcha, add them to both scripts. For example if the script URL ends with ?hl=fr, add that to both the new script URLs.

  2. Replace h-captcha with frc-captcha and update the sitekey

    <div class="h-captcha" data-sitekey="<hCaptcha sitekey>"></div>

    becomes

    <div class="frc-captcha" data-sitekey="<Friendly Captcha sitekey>"></div>

Update your server's integration​

Follow the guide here to set up your server's integration.

Compatibility notes (only relevant for advanced usage)​

Making use of the compatibility scripts (hcaptcha-site.min.js and hcaptcha-site.compat.min.js) means that the Friendly Captcha widget will work without having to change any Javascript code on your website or web app.

Some fields and methods do behave differently, here is a list of the different behavior:

Container Configuration and render attributes (docs)​

  • data-size has no effect. The Friendly Captcha widget is fully responsive, you can make it any size you want. You can use plain CSS to resize it.
  • data-chalexpired-callback is never called, instead data-expired-callback is called when the captcha response expires.
  • data-open-callback is called when the widget starts solving.
  • data-close-callback has no effect and is never called. In hCaptcha this is called when the user closes the "click-the-pictures" challenge, which is not relevant.

Javascript API (docs)​

  • hcaptcha.getRespKey(widgetID)(docs) always returns an empty string.