Integrate reCAPTCHA with Android apps

This page explains how to integrate reCAPTCHA in your Android app.

If you want to provide visual challenges for suspicious traffic, you can use the SafetyNet reCAPTCHA API.

The SDK uses reflection and dynamic code to allow modification and refinement of the detection system in the existing deployed applications/SDKs. The set of classes that are available in the system are restricted to a controlled list to avoid interference with the application.

Before you begin

1. Prepare your environment for reCAPTCHA.

2. Create a reCAPTCHA Key for the Android app platform.

   Alternatively, you can copy the ID of an existing reCAPTCHA key for Android 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 content_copy .
   • 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.

Prepare your Android environment

Integrate reCAPTCHA with your Android app

1. Instantiate a client by using the reCAPTCHA key (KEY_ID) that you created for your Android app.

   Kotlin with fetchClient

   The fetchClient method returns a client immediately and starts initializing the SDK in the background. It retries the communication with the reCAPTCHA server on network failures.

   class CustomApplication : Application() {
   
       private lateinit var recaptchaClient: RecaptchaClient
   
       override fun onCreate() {
         super.onCreate()
         initializeRecaptchaClient()
       }
   
       private fun initializeRecaptchaClient() {
         lifecycleScope.launch {
           try {
             recaptchaClient = Recaptcha.fetchClient(application, "KEY_ID")
           } catch(e: RecaptchaException) {
             // Handle errors ...
             // See "Handle errors" section
           }
         }
       }
   }
   

   Java with fetchClient

   public final class CustomApplication extends Application {
     @Nullable private RecaptchaTasksClient recaptchaTasksClient = null;
   
     @Override
     protected void onCreate() {
       super.onCreate();
       initializeRecaptchaClient();
     }
   
     private void initializeRecaptchaClient() {
       Recaptcha
         .fetchTaskClient(getApplication(), "KEY_ID")
         .addOnSuccessListener(
             this,
             new OnSuccessListener<RecaptchaTasksClient>() {
               @Override
               public void onSuccess(RecaptchaTasksClient client) {
                 MainActivity.this.recaptchaTasksClient = client;
               }
             })
         .addOnFailureListener(
             this,
             new OnFailureListener() {
               @Override
               public void onFailure(@NonNull Exception e) {
                 // Handle errors ...
                 // See "Handle errors" section
               }
             });
     }
   }
   

   Initialization of the SDK can take several seconds to complete. To mitigate this latency, initialize the client as early as possible, such as during the onCreate() call of a custom Application class. You shouldn't make UI elements block on the reCAPTCHA SDK.

2. For each action of your app that is protected using reCAPTCHA, call the execute method passing a RecaptchaAction. reCAPTCHA provides a built-in set of actions and if necessary you can create custom actions.

   The following code snippet shows how to use execute to protect a LOGIN action.

   Kotlin

   private fun executeLoginAction() {
     lifecycleScope.launch {
       recaptchaClient
         .execute(RecaptchaAction.LOGIN)
         .onSuccess { token ->
           // Handle success ...
           // See "What's next" section for instructions
           // about handling tokens.
         }
         .onFailure { exception ->
           // Handle errors ...
         }
     }
   }
   

   Java

   private void executeLoginAction(View v) {
     assert recaptchaTasksClient != null;
     recaptchaTasksClient
       .executeTask(RecaptchaAction.LOGIN)
       .addOnSuccessListener(
           this,
           new OnSuccessListener<String>() {
             @Override
             public void onSuccess(String token) {
               // Handle success ...
               // See "What's next" section for instructions
               // about handling tokens.
             }
           })
       .addOnFailureListener(
           this,
           new OnFailureListener() {
             @Override
             public void onFailure(@NonNull Exception e) {
               // Handle errors ...
             }
           });
   }
   

Migrate from getClient method to fetchClient method

The fetchClient method returns a RecaptchaClient that retries initialization over network failures. If the app doesn't have network access when the client is created, the client keeps retrying and successfully initializes when a network is acquired.

If you call execute(timeout) and the client is not yet ready, it tries to initialize before returning a token or a RecaptchaErrorCode.

The following example shows how to migrate from getClient to fetchClient.

// Migrate from getClient
private fun initializeWithGetClient() {
  lifecycleScope.launch {
    Recaptcha.getClient(application, "KEY_ID")
      .onSuccess { client ->
        recaptchaClient = client
      }
      .onFailure { exception ->
        // Handle errors ...
      }
  }
}

 // Migrate to fetchClient
private fun initializeWithFetchClient() {
  lifecycleScope.launch {
    try {
      recaptchaClient = Recaptcha.fetchClient(application, "KEY_ID")
    } catch(e: RecaptchaException){
      // Handle errors ...
    }
  }
}

  // Migrate from getTasksClient
  private void initializeWithGetTasksClient() {
    Recaptcha
      .getTasksClient(getApplication(), "KEY_ID")
      .addOnSuccessListener(
          this,
          new OnSuccessListener<RecaptchaTasksClient>() {
            @Override
            public void onSuccess(RecaptchaTasksClient client) {
              recaptchaTasksClient = client;
            }
          })
      .addOnFailureListener(
          this,
          new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
              // Handle errors ...
            }
          });
  }

  // Migrate to fetchTaskClient
  private void initializeWithFetchTaskClient() {
    Recaptcha
      .fetchTaskClient(getApplication(), "KEY_ID")
      .addOnSuccessListener(
          this,
          new OnSuccessListener<RecaptchaTasksClient>() {
            @Override
            public void onSuccess(RecaptchaTasksClient client) {
              recaptchaTasksClient = client;
            }
          })
      .addOnFailureListener(
          this,
          new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
              // Handle errors ...
            }
          });
  }

Set a timeout for API calls

You can specify a timeout value for the execute APIs by using the withTimeout property.

Handle errors

If your app cannot communicate with the reCAPTCHA service successfully, it might be because the API encountered an error. You must add logic in your app to gracefully handle such errors.

For more details about mitigations for common API errors, see RecaptchaErrorCode.

API reference

For a complete reference of the reCAPTCHA API for Android, see com.google.android.recaptcha.

What's next

• To assess the reCAPTCHA response token, create an assessment.