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
Choose the best method for setting up reCAPTCHA Enterprise in your environment and complete the setup.
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:
Go to the reCAPTCHA Enterprise page.
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:
- Add verification on a user interaction
- Add verification when the page loads
- Add reCAPTCHA on an HTML button
You can see an example of each option in the source code of the demo website.
Add verification on a user interaction
-
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>
To add reCAPTCHA Enterprise verification on a user interaction, do the following:
To ensure that
grecaptcha.enterprise.execute()
runs when the reCAPTCHA library loads, usegrecaptcha.enterprise.ready()
.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 theaction
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
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
-
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>
To add reCAPTCHA Enterprise verification when the page loads, do the following:
To ensure that
grecaptcha.enterprise.execute()
runs when the reCAPTCHA library loads, usegrecaptcha.enterprise.ready()
.Call
grecaptcha.enterprise.execute()
with your score-based site key and specify a meaningful name for a user interaction in theaction
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>
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
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>
To add reCAPTCHA Enterprise on a simple HTML button, do the following:
Define a callback function to handle the token.
<script> function onSubmit(token) { document.getElementById("demo-form").submit(); } </script>
Add attributes to your html button.
<button class="g-recaptcha" data-sitekey="site_key" data-callback='onSubmit' data-action='submit'>Submit</button>
When this button is used to submit a form on your site, the
g-recaptcha-response
POST parameter contains the response token.
After the token is generated, send the reCAPTCHA token to your backend and create an assessment within two minutes.
What's next
- To assess the reCAPTCHA response token, create an assessment.