Create an assessment

This document shows you how to create an assessment to allow your backend to verify the authenticity of the token that reCAPTCHA Enterprise sends. reCAPTCHA Enterprise sends an encrypted response called token when the end user triggers an HTML action.

For any type of site key integration (checkbox or score), you must create an assessment to assess the results of execute() in your backend. You create an assessment by submitting the generated token to the assessment endpoint. reCAPTCHA Enterprise processes the submitted token, and reports the token's validity and score.

Important: If you do not create assessments in the backend, attackers can forge the request sent from the browser and make your application vulnerable to abuse and fraudulent activities. We do not recommend using an API key or a legacy secret key on your frontend because this can allow attackers to abuse your application.

The first 1 million reCAPTCHA Enterprise monthly assessments are free. To continue creating assessments after you reach the free monthly usage limit (1 million assessments per month), you must enable billing for your Google Cloud project. For more information about billing for reCAPTCHA Enterprise, see Billing information.

Before you begin

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

Retrieve the user's response token

Retrieve the user's response token from the web pages in one of following ways:

• The resolved value of the promise returned by the call to grecaptcha.enterprise.execute().
• g-recaptcha-response POST parameter when a user submits the form on your site.
• As a string argument to your callback function if data-callback is specified in either the g-recaptcha HTML tag attribute or the callback parameter in the grecaptcha.enterprise.render method.

To retrieve user's response token from mobile applications, see Integrating reCAPTCHA Enterprise with iOS apps or Integrating reCAPTCHA Enterprise with Android apps.

You can access each user's reCAPTCHA response token only once. If you need to assess a subsequent action that a user takes on your site, or if a token expires before an assessment is created, you must call execute() again to generate a new token.

Note: Tokens are valid for two minutes or for one use.

Create an assessment

Create an assessment by sending a request to the reCAPTCHA Enterprise API, or by using the reCAPTCHA Enterprise Client Libraries. We recommend that you choose the method to create an assessment based on where you have set up reCAPTCHA Enterprise.

Choose how to create an assessment

The methods you can use for creating an assessment depend on your environment. The following table lists supported environments and their corresponding assessment methods:

Environment	Methods for creating an assessment
Google Cloud App Engine or GKE	reCAPTCHA Enterprise Client Libraries
Google Cloud Compute Engine	Either of the following: reCAPTCHA Enterprise REST API, using the gcloud CLI for authentication reCAPTCHA Enterprise Client Libraries
Third-party cloud or on-premises that support service accounts	Either of the following: reCAPTCHA Enterprise REST API, using the gcloud CLI for authentication reCAPTCHA Enterprise Client Libraries
Third-party cloud or on-premises that do not support service accounts	reCAPTCHA Enterprise REST API, using API keys for authentication
Migrated environment using additional reCAPTCHA Enterprise features, such as Multi-factor authentication (MFA)	Either of the following: reCAPTCHA Enterprise REST API, using the gcloud CLI for authentication reCAPTCHA Enterprise REST API, using API keys for authentication

Create an assessment using the REST API or Client Libraries

After you select the appropriate method for creating an assessment, perform the following steps to create an assessment. The way you create an assessment is the same for score-based and checkbox site keys.

Note: If you set up reCAPTCHA Enterprise on a third-party cloud or on-premises that do not support service accounts, you cannot use the reCAPTCHA Enterprise Client Libraries to create an assessment.

REST API

Create an assessment by sending a request to the reCAPTCHA Enterprise API. You can use either the gcloud CLI or API key for authentication.

Authenticate with the gcloud CLI

Create an assessment using the projects.assessments.create method. Send this request to the v1 API endpoint.

Before using any of the request data, make the following replacements:

• PROJECT_ID: your Google Cloud project ID
• TOKEN: token returned from the grecaptcha.enterprise.execute() call
• KEY: reCAPTCHA key associated with the site/app. For more information, see reCAPTCHA keys.
• USER_ACTION (for score-based site key integrations only): the user-initiated action that you specified for action in the grecaptcha.enterprise.execute() call, such as login. For more information, see Actions.
  Note: Actions are not supported for checkbox site key integrations.

HTTP method and URL:

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments

Request JSON body:

{
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY",
    "expectedAction": "USER_ACTION"
  }
}

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by executing gcloud init or gcloud auth login, or by using Cloud Shell, which automatically logs you into the gcloud CLI. You can check the currently active account by executing gcloud auth list.

Save the request body in a file called request.json, and execute the following command:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments"

PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by executing gcloud init or gcloud auth login, or by using Cloud Shell, which automatically logs you into the gcloud CLI. You can check the currently active account by executing gcloud auth list.

Save the request body in a file called request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "tokenProperties": {
    "valid": true,
    "hostname": "www.google.com",
    "action": "homepage",
    "createTime": "2019-03-28T12:24:17.894Z"
   },
  "riskAnalysis": {
    "score": 0.1,
    "reasons": ["AUTOMATION"]
  },
 "event": {
    "token": "TOKEN",
    "siteKey": "KEY",
    "expectedAction": "USER_ACTION"
  },
  "name": "projects/PROJECT_ID/assessments/b6ac310000000000"
}

Note: For a score-based site key integration, verify that the return value of action matches expectedAction when calling the projects.assessments.create method. If there is a mismatch, it indicates that an attacker is attempting to falsify actions. You can take actions against the user interaction, such as adding additional verifications or blocking the interaction to prevent any fraudulent activities.

We recommend using any JSON parsers in the non-strict parsing mode to prevent any outages if any additional fields are introduced to the JSON response.

Authenticate with an API key

Create an assessment using the projects.assessments.create method.

Note: If you are using the v1beta1 version of the API, we recommend using the v1 version because the new features, such as reCAPTCHA Enterprise account defender are available only on v1 version. For migrating from v1beta1 to v1, see Migrate from v1beta API to v1 API .

Before using any of the request data, make the following replacements:

• API_KEY: API key associated with the current project
• PROJECT_ID: your Google Cloud project ID
• TOKEN: token returned from the grecaptcha.enterprise.execute() call
• KEY: reCAPTCHA key associated with the site/app. For more information, see reCAPTCHA keys.
• USER_ACTION (for score-based site key integrations only): the user-initiated action that you specified for action in the grecaptcha.enterprise.execute() call, such as login. For more information, see Actions.
  Note: Actions are not supported for checkbox site key integrations.

HTTP method and URL:

POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY

Request JSON body:

{
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY",
    "expectedAction": "USER_ACTION"
  }
}

To send your request, choose one of these options:

curl

Note: Create an API key to authenticate with the API.

Save the request body in a file called request.json, and execute the following command:

curl -X POST \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY"

PowerShell

Note: Create an API key to authenticate with the API.

Save the request body in a file called request.json, and execute the following command:

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "tokenProperties": {
    "valid": true,
    "hostname": "www.google.com",
    "action": "homepage",
    "createTime": "2019-03-28T12:24:17.894Z"
   },
  "riskAnalysis": {
    "score": 0.1,
    "reasons": ["AUTOMATION"]
  },
  "event": {
    "token": "TOKEN",
    "siteKey": "KEY",
    "expectedAction": "USER_ACTION"
  },
  "name": "projects/PROJECT_ID/assessments/b6ac310000000000"
}

Note: For a score-based site key integration, verify that the return value of action matches expectedAction when calling the projects.assessments.create method. If there is a mismatch, it indicates that an attacker is attempting to falsify actions. You can take actions against the user interaction, such as adding additional verifications or blocking the interaction to prevent any fraudulent activities.

We recommend using any JSON parsers in the non-strict parsing mode to prevent outages in case of any additional fields being introduced to the JSON response.

C#

   using System;
   using Google.Api.Gax.ResourceNames;
   using Google.Cloud.RecaptchaEnterprise.V1;

   public class CreateAssessmentSample
   {
       // Create an assessment to analyze the risk of an UI action.
       // projectID: GCloud Project ID.
       // recaptchaSiteKey: Site key obtained by registering a domain/app to use recaptcha.
       // token: The token obtained from the client on passing the recaptchaSiteKey.
       // recaptchaAction: Action name corresponding to the token.
       public void createAssessment(string projectID = "project-id", string recaptchaSiteKey = "recaptcha-site-key",
           string token = "action-token", string recaptchaAction = "action-name")
       {

           // Create the client.
           // TODO: To avoid memory issues, move this client generation outside
           // of this example, and cache it (recommended) or call client.close()
           // before exiting this method.
           RecaptchaEnterpriseServiceClient client = RecaptchaEnterpriseServiceClient.Create();

           ProjectName projectName = new ProjectName(projectID);

           // Build the assessment request.
           CreateAssessmentRequest createAssessmentRequest = new CreateAssessmentRequest()
           {
               Assessment = new Assessment()
               {
                   // Set the properties of the event to be tracked.
                   Event = new Event()
                   {
                       SiteKey = recaptchaSiteKey,
                       Token = token,
                       ExpectedAction = recaptchaAction
                   },
               },
               ParentAsProjectName = projectName
           };

           Assessment response = client.CreateAssessment(createAssessmentRequest);

           // Check if the token is valid.
           if (response.TokenProperties.Valid == false)
           { 
               System.Console.WriteLine("The CreateAssessment call failed because the token was: " +
                   response.TokenProperties.InvalidReason.ToString());
               return;
           }

           // Check if the expected action was executed.
           if (response.TokenProperties.Action != recaptchaAction)
           {
               System.Console.WriteLine("The action attribute in reCAPTCHA tag is: " +
                   response.TokenProperties.Action.ToString());
               System.Console.WriteLine("The action attribute in the reCAPTCHA tag does not " +
                   "match the action you are expecting to score");
               return;
           }

           // Get the risk score and the reason(s).
           // For more information on interpreting the assessment,
           // see: https://cloud.google.com/recaptcha-enterprise/docs/interpret-assessment
           System.Console.WriteLine("The reCAPTCHA score is: " + ((decimal)response.RiskAnalysis.Score));

           foreach (RiskAnalysis.Types.ClassificationReason reason in response.RiskAnalysis.Reasons)
           {
               System.Console.WriteLine(reason.ToString());
           }
       }

       public static void Main(string[] args)
       {
           new CreateAssessmentSample().createAssessment();
       }
   }

Go

   import (
     "context"
     "fmt"

     recaptcha "cloud.google.com/go/recaptchaenterprise/apiv1"
     recaptchapb "google.golang.org/genproto/googleapis/cloud/recaptchaenterprise/v1"
   )

   func main() {
     // TODO(developer): Replace these variables before running the sample.
     projectID := "project-id"
     recaptchaSiteKey := "recaptcha-site-key"
     token := "action-token"
     recaptchaAction := "action-name"

     createAssessment(projectID, recaptchaSiteKey, token, recaptchaAction)
   }

   /**
   * Create an assessment to analyze the risk of an UI action.
   *
   * @param projectID: GCloud Project ID
   * @param recaptchaSiteKey: Site key obtained by registering a domain/app to use recaptcha services.
   * @param token: The token obtained from the client on passing the recaptchaSiteKey.
   * @param recaptchaAction: Action name corresponding to the token.
   */
   func createAssessment(projectID string, recaptchaSiteKey string, token string, recaptchaAction string) {

     // Create the recaptcha client.
     // TODO: To avoid memory issues, move this client generation outside
     // of this example, and cache it (recommended) or call client.close()
     // before exiting this method.
     ctx := context.Background()
     client, err := recaptcha.NewClient(ctx)
     if err != nil {
       fmt.Printf("Error creating reCAPTCHA client\n")
     }
     defer client.Close()

     // Set the properties of the event to be tracked.
     event := &recaptchapb.Event{
       Token:          token,
       SiteKey:        recaptchaSiteKey,
     }

     assessment := &recaptchapb.Assessment{
       Event: event,
     }

     // Build the assessment request.
     request := &recaptchapb.CreateAssessmentRequest{
       Assessment: assessment,
       Parent:     fmt.Sprintf("projects/%s", projectID),
     }

     response, err := client.CreateAssessment(
       ctx,
       request)

     if err != nil {
       fmt.Printf("%v", err.Error())
     }

     // Check if the token is valid.
     if response.TokenProperties.Valid == false {
       fmt.Printf("The CreateAssessment() call failed because the token"+
          " was invalid for the following reasons: %v",
       response.TokenProperties.InvalidReason)
       return
     }

     // Check if the expected action was executed.
     if response.TokenProperties.Action == recaptchaAction {
       // Get the risk score and the reason(s).
       // For more information on interpreting the assessment,
       // see: https://cloud.google.com/recaptcha-enterprise/docs/interpret-assessment
       fmt.Printf("The reCAPTCHA score for this token is:  %v",
         response.RiskAnalysis.Score)

       for _,reason := range response.RiskAnalysis.Reasons {
         fmt.Printf(reason.String()+"\n")
       }
       return
     }

     fmt.Printf("The action attribute in your reCAPTCHA tag does " +
         "not match the action you are expecting to score")
   }

Java

View on GitHub Feedback

import com.google.cloud.recaptchaenterprise.v1.RecaptchaEnterpriseServiceClient;
import com.google.recaptchaenterprise.v1.Assessment;
import com.google.recaptchaenterprise.v1.CreateAssessmentRequest;
import com.google.recaptchaenterprise.v1.Event;
import com.google.recaptchaenterprise.v1.ProjectName;
import com.google.recaptchaenterprise.v1.RiskAnalysis.ClassificationReason;
import java.io.IOException;

public class CreateAssessment {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectID = "project-id";
    String recaptchaSiteKey = "recaptcha-site-key";
    String token = "action-token";
    String recaptchaAction = "action-name";

    createAssessment(projectID, recaptchaSiteKey, token, recaptchaAction);
  }

  /**
   * Create an assessment to analyze the risk of an UI action. Assessment approach is the same for
   * both 'score' and 'checkbox' type recaptcha site keys.
   *
   * @param projectID : GCloud Project ID
   * @param recaptchaSiteKey : Site key obtained by registering a domain/app to use recaptcha
   *     services. (score/ checkbox type)
   * @param token : The token obtained from the client on passing the recaptchaSiteKey.
   * @param recaptchaAction : Action name corresponding to the token.
   */
  public static void createAssessment(
      String projectID, String recaptchaSiteKey, String token, String recaptchaAction)
      throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the `client.close()` method on the client to safely
    // clean up any remaining background resources.
    try (RecaptchaEnterpriseServiceClient client = RecaptchaEnterpriseServiceClient.create()) {

      // Set the properties of the event to be tracked.
      Event event = Event.newBuilder().setSiteKey(recaptchaSiteKey).setToken(token).build();

      // Build the assessment request.
      CreateAssessmentRequest createAssessmentRequest =
          CreateAssessmentRequest.newBuilder()
              .setParent(ProjectName.of(projectID).toString())
              .setAssessment(Assessment.newBuilder().setEvent(event).build())
              .build();

      Assessment response = client.createAssessment(createAssessmentRequest);

      // Check if the token is valid.
      if (!response.getTokenProperties().getValid()) {
        System.out.println(
            "The CreateAssessment call failed because the token was: "
                + response.getTokenProperties().getInvalidReason().name());
        return;
      }

      // Check if the expected action was executed.
      // (If the key is checkbox type and 'action' attribute wasn't set, skip this check.)
      if (!response.getTokenProperties().getAction().equals(recaptchaAction)) {
        System.out.println(
            "The action attribute in reCAPTCHA tag is: "
                + response.getTokenProperties().getAction());
        System.out.println(
            "The action attribute in the reCAPTCHA tag "
                + "does not match the action ("
                + recaptchaAction
                + ") you are expecting to score");
        return;
      }

      // Get the reason(s) and the risk score.
      // For more information on interpreting the assessment,
      // see: https://cloud.google.com/recaptcha-enterprise/docs/interpret-assessment
      for (ClassificationReason reason : response.getRiskAnalysis().getReasonsList()) {
        System.out.println(reason);
      }

      float recaptchaScore = response.getRiskAnalysis().getScore();
      System.out.println("The reCAPTCHA score is: " + recaptchaScore);

      // Get the assessment name (id). Use this to annotate the assessment.
      String assessmentName = response.getName();
      System.out.println(
          "Assessment name: " + assessmentName.substring(assessmentName.lastIndexOf("/") + 1));
    }
  }
}

Node.js

   const {RecaptchaEnterpriseServiceClient} =
        require('@google-cloud/recaptcha-enterprise');

   /**
   * Create an assessment to analyze the risk of an UI action. Note that
   * this example does set error boundaries and returns `null` for
   * exceptions.
   *
   * projectID: GCloud Project ID
   * recaptchaSiteKey: Site key obtained by registering a domain/app to use recaptcha services.
   * token: The token obtained from the client on passing the recaptchaSiteKey.
   * recaptchaAction: Action name corresponding to the token.
   */
   async function createAssessment({
     projectID = "your-project-id",
     recaptchaSiteKey = "your-recaptcha-site-key",
     token = "action-token",
     recaptchaAction = "action-name",
   }) {
     // Create the reCAPTCHA client & set the project path. There are multiple
     // ways to authenticate your client. For more information see:
     // https://cloud.google.com/docs/authentication
     // TODO: To avoid memory issues, move this client generation outside
     // of this example, and cache it (recommended) or call client.close()
     // before exiting this method.
     const client = new RecaptchaEnterpriseServiceClient();
     const projectPath = client.projectPath(projectID);

     // Build the assessment request.
     const request = ({
       assessment: {
         event: {
           token: token,
           siteKey: recaptchaSiteKey,
         },
       },
       parent: projectPath,
     });

     // client.createAssessment() can return a Promise or take a Callback
     const [ response ] = await client.createAssessment(request);

     // Check if the token is valid.
     if (!response.tokenProperties.valid) {
      console.log("The CreateAssessment call failed because the token was: " +
        response.tokenProperties.invalidReason);

      return null;
     }

     // Check if the expected action was executed.
     // The `action` property is set by user client in the
     // grecaptcha.enterprise.execute() method.
     if (response.tokenProperties.action === recaptchaAction) {

      // Get the risk score and the reason(s).
      // For more information on interpreting the assessment,
      // see: https://cloud.google.com/recaptcha-enterprise/docs/interpret-assessment
      console.log("The reCAPTCHA score is: " +
        response.riskAnalysis.score);

      response.riskAnalysis.reasons.forEach((reason) => {
        console.log(reason);
      });
      return response.riskAnalysis.score;
     } else {
      console.log("The action attribute in your reCAPTCHA tag " +
        "does not match the action you are expecting to score");
      return null;
     }
   }

PHP

 <?php

   // Include Google Cloud dependencies using Composer
   require 'vendor/autoload.php';

   use Google\Cloud\RecaptchaEnterprise\V1\RecaptchaEnterpriseServiceClient;
   use Google\Cloud\RecaptchaEnterprise\V1\Event;
   use Google\Cloud\RecaptchaEnterprise\V1\Assessment;
   use Google\Cloud\RecaptchaEnterprise\V1\TokenProperties\InvalidReason;

   /**
   * Create an assessment to analyze the risk of a UI action.
   * @param string $siteKey The key ID for the reCAPTCHA key (See https://cloud.google.com/recaptcha-enterprise/docs/create-key)
   * @param string $token The user's response token for which you want to receive a reCAPTCHA score. (See https://cloud.google.com/recaptcha-enterprise/docs/create-assessment#retrieve_token)
   * @param string $project Your Google Cloud project ID
   */
   function create_assessment(
      string $siteKey,
      string $token,
      string $project
   ): void {
       // TODO: To avoid memory issues, move this client generation outside
       // of this example, and cache it (recommended) or call client.close()
       // before exiting this method.
      $client = new RecaptchaEnterpriseServiceClient();
      $projectName = $client->projectName($project);

      $event = (new Event())
          ->setSiteKey($siteKey)
          ->setToken($token);

      $assessment = (new Assessment())
          ->setEvent($event);

      try {
          $response = $client->createAssessment(
              $projectName,
              $assessment
          );

          // You can use the score only if the assessment is valid,
          // In case of failures like re-submitting the same token, getValid() will return false
          if ($response->getTokenProperties()->getValid() == false) {
              printf('The CreateAssessment() call failed because the token was invalid for the following reason: ');
              printf(InvalidReason::name($response->getTokenProperties()->getInvalidReason()));
          } else {
              printf('The score for the protection action is:');
              printf($response->getRiskAnalysis()->getScore());

              // Optional: You can use the following methods to get more data about the token
              // Action name provided at token generation.
              // printf($response->getTokenProperties()->getAction() . PHP_EOL);
              // The timestamp corresponding to the generation of the token.
              // printf($response->getTokenProperties()->getCreateTime()->getSeconds() . PHP_EOL);
              // The hostname of the page on which the token was generated.
              // printf($response->getTokenProperties()->getHostname() . PHP_EOL);
          }
      } catch (exception $e) {
          printf('CreateAssessment() call failed with the following error: ');
          printf($e);
      }
   }

   // TODO(Developer): Replace the following before running the sample
   create_assessment(
      'YOUR_RECAPTCHA_SITE_KEY',
      'YOUR_USER_RESPONSE_TOKEN',
      'YOUR_GOOGLE_CLOUD_PROJECT_ID'
   );
 ?>

Python

View on GitHub Feedback

from google.cloud import recaptchaenterprise_v1
from google.cloud.recaptchaenterprise_v1 import Assessment


def create_assessment(
    project_id: str, recaptcha_site_key: str, token: str, recaptcha_action: str
) -> Assessment:
    """Create an assessment to analyze the risk of a UI action.
    Args:
        project_id: GCloud Project ID
        recaptcha_site_key: Site key obtained by registering a domain/app to use recaptcha services.
        token: The token obtained from the client on passing the recaptchaSiteKey.
        recaptcha_action: Action name corresponding to the token.
    """

    client = recaptchaenterprise_v1.RecaptchaEnterpriseServiceClient()

    # Set the properties of the event to be tracked.
    event = recaptchaenterprise_v1.Event()
    event.site_key = recaptcha_site_key
    event.token = token

    assessment = recaptchaenterprise_v1.Assessment()
    assessment.event = event

    project_name = f"projects/{project_id}"

    # Build the assessment request.
    request = recaptchaenterprise_v1.CreateAssessmentRequest()
    request.assessment = assessment
    request.parent = project_name

    response = client.create_assessment(request)

    # Check if the token is valid.
    if not response.token_properties.valid:
        print(
            "The CreateAssessment call failed because the token was "
            + "invalid for for the following reasons: "
            + str(response.token_properties.invalid_reason)
        )
        return

    # Check if the expected action was executed.
    if response.token_properties.action != recaptcha_action:
        print(
            "The action attribute in your reCAPTCHA tag does"
            + "not match the action you are expecting to score"
        )
        return
    else:
        # Get the risk score and the reason(s)
        # For more information on interpreting the assessment,
        # see: https://cloud.google.com/recaptcha-enterprise/docs/interpret-assessment
        for reason in response.risk_analysis.reasons:
            print(reason)
        print(
            "The reCAPTCHA score for this token is: "
            + str(response.risk_analysis.score)
        )
        # Get the assessment name (id). Use this to annotate the assessment.
        assessment_name = client.parse_assessment_path(response.name).get("assessment")
        print(f"Assessment name: {assessment_name}")
    return response

Ruby

View on GitHub Feedback

require "google/cloud/recaptcha_enterprise"

# Create an assessment to analyze the risk of a UI action.
#
# @param site_key [String] Site key obtained by registering a domain/app to use recaptcha services.
# @param token [String] The token obtained from the client on passing the recaptcha site_key.
# @param project_id [String] GCloud Project ID.
# @param recaptcha_action [String] Action name corresponding to the token.
# @return [void]
def create_assessment site_key:, token:, project_id:, recaptcha_action:
  # Create the reCAPTCHA client.
  client = ::Google::Cloud::RecaptchaEnterprise.recaptcha_enterprise_service

  request = { parent: "projects/#{project_id}",
              assessment: {
                event: {
                  site_key: site_key,
                  token: token
                }
              } }

  response = client.create_assessment request

  # Check if the token is valid.
  if !response.token_properties.valid
    puts "The create_assessment() call failed because the token was invalid with the following reason:" \
         "#{response.token_properties.invalid_reason}"
  # Check if the expected action was executed.
  elsif response.token_properties.action == recaptcha_action
    # Get the risk score and the reason(s).
    # For more information on interpreting the assessment,
    # see: https://cloud.google.com/recaptcha-enterprise/docs/interpret-assessment
    puts "The reCAPTCHA score for this token is: #{response.risk_analysis.score}"
    response.risk_analysis.reasons.each { |reason| puts reason }
  else
    puts "The action attribute in your reCAPTCHA tag does not match the action you are expecting to score"
  end
end

Note: Your assessment's response might show score=0.9 and reason=LOW_CONFIDENCE. This is because when you integrate a newly created key on your frontend, reCAPTCHA Enterprise takes some time to return accurate risk analysis. Therefore, for the accurate risk analysis, after creating and integrating keys on your frontend, we recommend you to wait for 48 hours before taking any action on the returned scores.

What's next

• Interpret an assessment and take an appropriate action for your site based on the score.