Installing score-based site keys (no challenge) on websites

This page explains how to install a score-based site key with no challenge on your website. With the score-based site key, you can include reCAPTCHA Enterprise throughout your site without requiring users to solve CAPTCHA challenges.

After you install a score-based site key, it returns a score for each request without user friction. Based on the score, you can understand the level of risk that user interactions pose and configure an appropriate response (or responses). Also, the score-based site key can collect bot activity telemetry for early warning against new attacks or targets.

To improve reCAPTCHA Enterprise's risk model, we recommend that you include reCAPTCHA Enterprise on every page of your site because it helps in understanding how real users and bots transition between different pages and actions.

Before you begin

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

  2. Create a score-based site key. Alternatively, you can copy the ID of an existing score-based site key by performing one of the following steps:

    • To copy the ID of an existing score-based site key from the Google Cloud Console, do the following:

      1. Go to the reCAPTCHA Enterprise page.

        Go to reCAPTCHA Enterprise

      2. In the reCAPTCHA keys list, hold the pointer over the key ID you want to copy, and then click .

    • To copy the ID of an existing score-based site key using the REST API, use the projects.keys.list method.

    • To copy the ID of an existing score-based site key using the gcloud tool, use the gcloud recaptcha keys list command.

Placing the key on your website

reCAPTCHA Enterprise works best when it has context about the interactions on your site. reCAPTCHA Enterprise monitors both legitimate and abusive behavior to learn about the interactions on your site.

For best results, install score-based site keys in the following places on your website:

  • Forms
  • Actions (user interactions)
  • In the background of all webpages

Score-based site keys do not interrupt your users, so you can run reCAPTCHA Enterprise with score-based site keys whenever required without affecting conversion.

Integrating the key with the frontend

  1. To load reCAPTCHA Enterprise on your webpage, add the JavaScript API with your score-based site key within the <head></head> element of your web page.
        <head>
        <script src="https://www.google.com/recaptcha/enterprise.js?render=site_key"></script>
        ....
        </head>
      
  2. Add reCAPTCHA Enterprise verification on a specific interaction (such as a button click, multiple interactions), or when the web page loads.

    When you specify the action parameter, the following features are enabled:

    • Adaptive risk analysis based on the context of the action because abusive behavior can vary.
    • Filtering and grouping of score metrics by action in Stackdriver.

    Depending on where you want to add reCAPTCHA Enterprise verification, choose the appropriate option:

    • If you want to add reCAPTCHA Enterprise verification on a user interaction, do the following:

      1. To ensure that grecaptcha.enterprise.execute() runs when the reCAPTCHA library loads, use grecaptcha.enterprise.ready().

      2. Call grecaptcha.enterprise.execute() on each interaction you want to protect with your score-based site key. Specify a meaningful name for a user interaction in the action parameter. For more guidance, see Actions.

        The following example shows how to call grecaptcha.enterprise.execute() on a login action:

           <script>
            function onClick(e) {
              e.preventDefault();
              grecaptcha.enterprise.ready(async () => {
                const token = await grecaptcha.enterprise.execute('site_key', {action: 'LOGIN'});
                // IMPORTANT: The 'token' that results from execute is an encrypted response sent by
                // reCAPTCHA Enterprise to the end user's browser.
                // This token must be validated by creating an assessment.
                // See https://cloud.google.com/recaptcha-enterprise/docs/create-assessment
              });
            }
           </script>
           

        grecaptcha.enterprise.execute() generates a token as shown in the following example:

        03AGdBq27tvcDrfiRuxQnyKs-SarXVzPODXLlpiwNsLqdm9BSQQRtxhkD-Wv6l2vBSnL_JQd80FZp3IeeF_TxNMrqhyQchk7hmg_ypDctt_F5RTr9zNO9TSDX3Fy0qHQTuaM9E3hrAkA1v1l7D-fCreg7uq8zoudfh1ZRmN49-2iAMAn4E8_ff-nmlLTNGVZmCSyeze-5xM24pM_JhhUVcCMIDKYtDUnr2imxg2ubIqMscCZGUtdXNUO_LRSzuwWDlLyAr3V2nVn29Z48PQa2QzbymEXzO9pCtoGQmY7kiZ8ILfD9DAJSSyUTMwJXVJptUeBmLM341fq_STYZBbPQJ0zYOEDvJoFsIwGMfuphkDet0nK56b0mkzaL8RCRy2oK31Mcx6n3PhGkCnQ6QIhiV5ZVmV1Hz9M3w99zYw6ekc3wPCNMZ6V6x1ApVpIk3reFfByRQ0C0_pRWwbKZHLXQ_oSTI1UI7kyH1VeXngsJAx2l7zcp0hQNipajC4YwL7Jb8X4cCD0NeiaY1YCrI5j87mK5axcMikq460I4niIFeDBlHGF-ndqu3CJstosAur-C_x827f-dPPjA9Vrw8MDb3x4KUb0vbA8xE9mJxPYGY0rPCR27vJ38Voa7DjEBGX9c-iufv5_wfj-yIfIAHy0iijnRLI0CVkWF2-iPdWv7LnkTwL3WKbF_MrEGZXmtyLX9dEZArfxmToeMuSdYkfikkgR2-k4Xzxlz15RbHJuWSAYqEyTTnpUXmOvDuTN92b0kYqbRelcLUI_Shm-8dq9e-L7K6YWQv32gV6NukZKY15dyrJaW10frBgTOGSTTpIyB7MNEL8S27WjWtOb-zWsgimIhoRNfS8BiJWkmK4gTj51m7Wur-qsDbHgV6gXlMvjJs_B7oXX-mKsKhY9ACtwukotBelGYQOvf1RDHjH3Yi1RDfELBY6AkwUK4tq8cACVGpCwa0gKUo-sbORTsGu_r7VTzYo1AaZD5HV4XUm8yoqszel6DmIfkJcI7PfzzvfUJuvMQ1itZSzpzuth3glbKBYsIjbKqG-q8cxtZ7u0l32j46ASo2zlCJWUjwP3W1P7MUenEoIZtjlyTB_tT6Fk8RxGgRv3oLP7NPFJGs9ZGOAl6tBHpZF8Y_FqEOCMKtBl2JYOE5h6_Es3buSdiMm7mtLr64pboGiEColF1vbVvYpyaaqGFPXBM6ekZSXEXLAI0_7rj_fCLgnB21KXfac95vZbM9vyJCASvDcWKwqajQwy5aGMNe9GtbMogYbZfz5UGWAIi24Vd8KSv3qKOOwvzbcw4H0HYdsBXA
        
      3. If you want to add reCAPTCHA Enterprise verification when the page loads, do the following:

        1. To ensure that grecaptcha.enterprise.execute() runs when the reCAPTCHA library loads, use grecaptcha.enterprise.ready().

        2. Call grecaptcha.enterprise.execute() with your score-based site key and specify a meaningful name for a user interaction in the action parameter. For more guidance, see Actions.

          The following example shows how to call grecaptcha.enterprise.execute() when loading a web page:

             <script  src="https://www.google.com/recaptcha/enterprise.js?render=site_key"></script>
             <script>
                grecaptcha.enterprise.ready(function() {
                    grecaptcha.enterprise.execute('site_key', {action: 'homepage'}).then(function(token) {
                       // IMPORTANT: The 'token' that results from execute is an encrypted response sent by
                       // reCAPTCHA Enterprise to the end user's browser.
                       // This token must be validated by creating an assessment.
                       // See https://cloud.google.com/recaptcha-enterprise/docs/create-assessment
                    });
                });
             </script>
              

      4. If you want to add reCAPTCHA Enterprise on a simple HTML button, do the following:

        1. To handle the token, add a callback() function.

              <script>
                 function onSubmit(token) {
                   document.getElementById("demo-form").submit();
                 }
              </script>
            

        2. Add attributes to your html button.

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

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

What's next