Install policy-based challenge keys on websites

This page explains how to install a policy-based challenge key on your website. With a policy-based challenge key, reCAPTCHA can deterministically trigger CAPTCHA challenges based on a score threshold and challenge difficulty.

Before you begin

  1. Prepare your environment for reCAPTCHA.

  2. Create a policy-based challenge key.

    Alternatively, you can copy the ID of an existing policy-based challenge key by performing one of the following steps:

    • To copy the ID of an existing key from the Google Cloud console, do the following:

      1. Go to the reCAPTCHA page.

        Go to reCAPTCHA

      2. In the reCAPTCHA keys list, hold the pointer over the key you want to copy, and then click .
    • To copy the ID of an existing key using the REST API, use the projects.keys.list method.
    • To copy the ID of an existing key using the gcloud CLI, use the gcloud recaptcha keys list command.

Configure the policy-based challenge key

For your policy-based challenge key, you must specify the challenge difficulty that determines the complexity and frequency of CAPTCHA challenges, and define a custom score threshold for specific actions that overrides the default threshold.

  1. In the Google Cloud console, go to the reCAPTCHA page.

    Go to reCAPTCHA

    The reCAPTCHA page has two views: Tables and Cards. If your project has many reCAPTCHA keys, only the Table view is available.

  2. Verify that the name of your project appears in the resource selector at the top of the page.

    If you don't see the name of your project, click the resource selector, and then select your project.

  3. In the reCAPTCHA keys section, identify the policy-based challenge key that you want to configure, and click the key.

  4. In the Key details page, go to the Overview tab.

  5. In the Configuration section, click Configure for Challenge settings.

  6. In the Configure challenge settings page, select the challenge difficulty.

  7. To trigger CAPTCHA challenges, use the slider to specify the default threshold value.

    The default threshold of 0.0 does not trigger any challenge. 1.0 triggers a challenge for every request.

  8. To configure a custom score threshold for individual actions, which overrides the default threshold value, do the following:

    1. Enter an action name.

    2. To specify a custom score threshold, use the Set action threshold slider.

    3. Click Done.

  9. Click Save.

Add reCAPTCHA on an HTML button

  1. To load reCAPTCHA on your web page, add the JavaScript API with your policy-based challenge key within the <head></head> element of your web page.

        <head>
    <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
    ....
    </head>

    reCAPTCHA uses the browser's language by default. If you want to specify a different language, use the hl=LANG attribute in your script. For example, to use French, specify the following: <script src="https://www.google.com/recaptcha/enterprise.js?hl=fr"></script>. To learn about the supported languages, see language codes for reCAPTCHA.

  2. To add reCAPTCHA on a simple HTML button, do the following:

    1. Define a callback function to handle the token.

      <script>
   function onSubmit(token) {
     document.getElementById("demo-form").submit();
   } // Use `requestSubmit()` for extra features like browser input validation.
</script>

      For more information, see requestSubmit() method.

    2. Add attributes to your html button.

      <button class="g-recaptcha"
data-sitekey="KEY_ID"
data-callback="onSubmit"
data-action="submit">Submit</button>

      If you want to specify a location for the badge, then use the data-badge=LOCATION attribute on the element that has class=g-recaptcha. By default, the location is set to bottomright. The other possible values are inline and bottomleft.

    3. When this button is used to submit a form on your site, the g-recaptcha-response POST parameter contains the response token.

  3. After the token is generated, send the reCAPTCHA token to your backend and create an assessment within two minutes.

What's next