Installing checkbox site keys (checkbox challenge) on websites

This page explains how to install a checkbox site 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 site key, reCAPTCHA Enterprise might require the end user to solve a CAPTCHA challenge before generating a valid token.

Before you begin

  1. Choose the best method for setting up reCAPTCHA Enterprise in your environment and complete the setup.

  2. Create a checkbox site key.

Rendering 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 site key.

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

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="site_key"></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 Enterprise 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 Enterprise 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": "your_site_key", "theme": "light"}.

      grecaptcha.enterprise.render('html_element', {
         'sitekey' : ' site_key',
       });
      
  2. To render the widget, insert the JavaScript resource. Set onload to the name of your onload callback function, and include render=explicit.

     <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' : ' site_key',
        });
      };
    </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' : 'site_key',
          'theme' : 'light'
        });
        widgetId2 = grecaptcha.enterprise.render(document.getElementById('example2'), {
          'sitekey' : 'site_key',
        });
        grecaptcha.enterprise.render('example3', {
          'sitekey' : 'site_key',
          '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