reCAPTCHA v3

This is a Beta version of reCAPTCHA which is still undergoing final testing before its official release. The API, documentation, and policy are subject to change in the future.

reCAPTCHA v3 returns a score for each request without user friction. The score is based on interactions with your site and enables you to take fine-grained action. Register reCAPTCHA v3 keys here.

This page explains how to enable and customize reCAPTCHA v3 on your webpage.

Frontend integration

  <script src="https://www.google.com/recaptcha/api.js?render=reCAPTCHA_site_key"></script>
  <script>
  grecaptcha.ready(function() {
      grecaptcha.execute('reCAPTCHA_site_key', {action: 'action_name'}).then(function(token) {
         ...
      });
  });
  </script>
  1. Load the JavaScript api with your sitekey
  2. Call grecaptcha.execute on an action or when the page loads
  3. Send the token to your backend with the request to verify

Tips

grecaptcha.ready() will run your function as soon as the reCAPTCHA library has loaded. To avoid race conditions with the api.js, either include the api.js before your scripts that call grecaptcha, or you can continue to use the onload callback defined with the v2 API.

Placement on your website

reCAPTCHA v3 will never interrupt your users, so you can run it whenever you like without affecting conversion. reCAPTCHA works best when it has the most context about interactions with your site, which comes from seeing both legitimate and abusive behavior. For this reason, we recommend including reCAPTCHA verification on forms or actions as well as in the background of pages for analytics.

Note: You can execute reCAPTCHA as many times as you'd like with different actions on the same page.

Interpreting the score

reCAPTCHA v3 returns a score (1.0 is very likely a good interaction, 0.0 is very likely a bot). Based on the score, you can take variable action in the context of your site. Every site is different, but below are some examples of how sites use the score. As in the examples below, take action behind the scenes instead of blocking traffic to better protect your site.

Use case Recommendation
homepage See a cohesive view of your traffic on the admin console while filtering scrapers.
login With low scores, require 2-factor-authentication or email verification to prevent brute force attacks.
social Limit unanswered friend requests from abusive users and send risky comments to moderation.
e-commerce Put your real sales ahead of bots and identify risky transactions.

To choose appropriate thresholds, we recommend looking at your traffic in the admin console. As reCAPTCHA v3 doesn't ever interrupt the user flow, you can first run reCAPTCHA without taking action and then set limits once you see your site's score distribution. For initial trials, you can set a threshold of 0.5.

Actions

reCAPTCHA v3 introduces a new concept: actions. When you specify an action name in each place you execute reCAPTCHA you enable two new features:

  • a detailed break-down of data for your top ten actions in the admin console
  • adaptive risk analysis based on the context of the action (abusive behavior can vary)

Importantly, when you verify the reCAPTCHA response you should also verify that the action name matches the one you expect.

  <script>
  grecaptcha.ready(function() {
      grecaptcha.execute('reCAPTCHA_site_key', {action: 'action_name'});
  });
  </script>

Note: actions may only contain alphanumeric characters and slashes, and must not be user-specific.

API Response

The response is a JSON object:

{
  "success": true|false,      // whether this request was a valid reCAPTCHA token for your site
  "score": number             // the score for this request (0.0 - 1.0)
  "action": string            // the action name for this request (important to verify)
  "challenge_ts": timestamp,  // timestamp of the challenge load (ISO format yyyy-MM-dd'T'HH:mm:ssZZ)
  "hostname": string,         // the hostname of the site where the reCAPTCHA was solved
  "error-codes": [...]        // optional
}