Install checkbox keys (checkbox challenge) on websites

This page explains how to install a checkbox key with the I'm not a robot checkbox challenge on your website. Depending on how you have configured the challenge security option when creating the checkbox key, reCAPTCHA might require the end user to solve a CAPTCHA challenge before generating a valid token.

Before you begin

  1. Prepare your environment for reCAPTCHA.

  2. Create a checkbox key.

    Alternatively, you can copy the ID of an existing checkbox 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.

Render the reCAPTCHA widget on the frontend

To display the reCAPTCHA widget on your web page, use one of the following methods:

Automatically render the widget

With this method, you can render the widget on any object (such as a div or a span) with the g-recaptcha class.

On your web page, include the necessary JavaScript resource and an HTML element with the g-recaptcha class.

In the element with the g-recaptcha class, also include the data-sitekey attribute and set it equal to your checkbox key.

To specify an action, include the data-action attribute and set it to an action name. For more guidance, see Actions.

The script must be loaded using the HTTPS protocol and can be included from any point on the page without restriction.

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.

The following example is a snippet of sample code:

    <html>
      <head>
        <title>reCAPTCHA demo: Simple page</title>
        <script src="https://www.google.com/recaptcha/enterprise.js" async defer></script>
      </head>
      <body>
        <form action="?" method="POST">
          <div class="g-recaptcha" data-sitekey="KEY_ID" data-action="LOGIN"></div>
          <br/>
          <input type="submit" value="Submit">
        </form>
      </body>
    </html>

Explicitly render the widget

With this method, you can render the widget through an existing JavaScript script using the grecaptcha.enterprise.render() method. Use this method to avoid race conditions or if you want to show the widget based on the existing JavaScript logic.

To ensure there are no race conditions when rendering the widget explicitly, review the following considerations:

  • Order your scripts with the callback function first, and then the reCAPTCHA API.
  • Use the async and defer parameters in the script tags.

To render the widget explicitly, follow these steps:

  1. To defer rendering of the widget, do the following:

    1. Specify your onload callback function before the reCAPTCHA API and other dependencies are loaded.

       <script type="text/javascript">
 var onloadCallback = function() {
    alert("grecaptcha is ready!");
 };
 </script>

    2. After your callback function is executed, call the grecaptcha.enterprise.render() method with the following parameters from the JavaScript API.

      • container: The HTML element to render the reCAPTCHA widget. Specify either the ID of the container (string) or the DOM element itself.

      • parameters: An object containing parameters as key-value pairs, for example, {"sitekey": "KEY_ID", "theme": "light"}.

      • action: Specify the action name associated with the protected element.

      grecaptcha.enterprise.render('html_element', {
   'sitekey' : 'KEY_ID',
   'action': 'LOGIN',
 });

  2. To render the widget, insert the JavaScript resource. Set onload to the name of your onload callback function, and include render=explicit.

    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.

     <script src="https://www.google.com/recaptcha/enterprise.js?onload=onload_Callback_function&render=explicit"
    async defer>
 </script>

Example 1

The following code sample shows explicit rendering after an onload callback:

<html>
   <head>
    <title>reCAPTCHA demo: Explicit render after an onload callback</title>
     <script type="text/javascript">
      var onloadCallback = function() {
        grecaptcha.enterprise.render('html_element', {
          'sitekey' : 'KEY_ID',
        });
      };
    </script>
  </head>
  <body>
    <form action="?" method="POST">
      <div id="html_element"></div>
      <br>
      <input type="submit" value="Submit">
    </form>
      <script src="https://www.google.com/recaptcha/enterprise.js?onload=onloadCallback&render=explicit"
        async defer>
    </script>
  </body>
</html>

Example 2

The following code sample shows explicit rendering of multiple widgets:

<html>
  <head>
    <title>reCAPTCHA demo: Explicit render for multiple widgets</title>
        <script type="text/javascript">
      var verifyCallback = function(response) {
        alert(response);
      };
      var widgetId1;
      var widgetId2;
      var onloadCallback = function() {
        // Renders the HTML element with id 'example1' as a reCAPTCHA widget.
        // The id of the reCAPTCHA widget is assigned to 'widgetId1'.
        widgetId1 = grecaptcha.enterprise.render('example1', {
          'sitekey' : 'KEY_ID',
          'theme' : 'light'
        });
        widgetId2 = grecaptcha.enterprise.render(document.getElementById('example2'), {
          'sitekey' : 'KEY_ID',
        });
        grecaptcha.enterprise.render('example3', {
          'sitekey' : 'KEY_ID',
          'callback' : verifyCallback,
          'theme' : 'dark'
        });
      };
    </script>
  </head>
  <body>
    <!-- The g-recaptcha-response string displays in an alert message upon submit. -->
    <form action="javascript:alert(grecaptcha.enterprise.getResponse(widgetId1));">
      <div id="example1"></div>
      <br>
      <input type="submit" value="getResponse">
    </form>
    <br>
    <!-- Resets reCAPTCHA widgetId2 upon submit. -->
    <form action="javascript:grecaptcha.enterprise.reset(widgetId2);">
      <div id="example2"></div>
      <br>
      <input type="submit" value="reset">
    </form>
    <br>
    <!-- POSTs back to the page's URL upon submit with a g-recaptcha-response POST parameter. -->
    <form action="?" method="POST">
      <div id="example3"></div>
      <br>
      <input type="submit" value="Submit">
    </form>
     <script src="https://www.google.com/recaptcha/enterprise.js?onload=onloadCallback&render=explicit"
        async defer>
    </script>
  </body>
</html>

What's next