Install score-based keys on websites

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

When a score-based key is installed, reCAPTCHA sends an encrypted response, the reCAPTCHA response token (also known as token), when an end user triggers an interaction. After the token is generated, you need to create an assessment within two minutes to receive a score for each request. 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 key can collect bot activity telemetry for early warning against new attacks or targets.

To improve reCAPTCHA's risk model, we recommend that you include reCAPTCHA 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. Prepare your environment for reCAPTCHA.

  2. Create a score-based key.

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

Place the key on your website

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

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

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

Score-based keys don't interrupt your users, so you can run reCAPTCHA with score-based keys whenever required without affecting conversion.

Integrate the key with the frontend

We recommend adding reCAPTCHA verification on a user interaction that needs to be verified. For example, if you want to verify the submit action of a form, then you need to add reCAPTCHA verification on the submit action.

Depending on where you want to add reCAPTCHA 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 on your web page, add the JavaScript API with your score-based 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.

    If you want to specify a location for the badge, then use badge=LOCATION as a query parameter in the script tag. For example, www.google.com/recaptcha/enterprise.js?sitekey=KEY_ID&badge=bottomleft. By default, the location is set to bottomright. The other possible values are inline and bottomleft.

  2. To add reCAPTCHA verification on a user interaction, do the following:

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

    2. Call grecaptcha.enterprise.execute() on each interaction you want to protect with your score-based 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('KEY_ID', {action: 'LOGIN'});
    // IMPORTANT: The 'token' that results from execute is an encrypted response sent by
    // reCAPTCHA to the end user's browser.
    // This token must be validated by creating an assessment.
    // See https://cloud.google.com/recaptcha/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.

    For WAF integrations, if you are integrating an action-token key, you must attach the token to a predefined request header and you need not create an assessment. For details, see Implement reCAPTCHA action-tokens.

Add reCAPTCHA on an HTML button

  1. To load reCAPTCHA on your web page, add the JavaScript API with your score-based 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.

    For WAF integrations, if you are integrating an action-token key, you must attach the token to a predefined request header and you need not create an assessment. For details, see Implement reCAPTCHA action-tokens.

What's next