Install 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 CLI, use the gcloud recaptcha keys list command.

Place 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.

Integrate the key with the frontend

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

You can see an example of each option in the source code of the demo website.

Add verification on a user interaction

  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. 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. After the token is generated, send the reCAPTCHA token to your backend and create an assessment within two minutes.

Add verification when the page loads

  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. 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(async () => {
    const token = await grecaptcha.enterprise.execute('site_key', {action: 'homepage'});
    // 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>

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

Add reCAPTCHA on an HTML button

  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. To add reCAPTCHA Enterprise 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();
   }
</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. 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