Integrate reCAPTCHA Enterprise with Android apps

This page explains how to integrate reCAPTCHA Enterprise in your Android app. Due to the variation in mobile devices in terms of screen size, performance, and UIs of the apps, the visual checkbox reCAPTCHA challenge (I'm not a robot) is not available for mobile apps. You can instead implement your own tiered enforcement strategy, such as an MFA flow to provide an alternative redemption path for suspicious traffic.

Important: 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. Choose the best method for setting up reCAPTCHA Enterprise in your environment and complete the setup.

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

Prepare your environment

Warning: Don't migrate to Android SDK 18.2.0, because it might make your app non-functional due to some internal errors. To avoid these problems, migrate directly to Android SDK 18.2.1 or later. For details, see the issue report on GitHub.

Native Android

1. Prepare your development environment by downloading and installing the latest version of Android Studio.

2. Ensure that you have an app with the minimum Android SDK value set to API 19: Android 4.4 (KitKat). You can either set the minimum SDK of your app to API 19 or create a new mobile app.

3. If you are creating a new mobile app, create a test application by starting a new Android Studio project:

   1. Select Empty Activity. If you want to use Jetpack Compose on your app choose Empty Compose Activity.
   2. Set the language to kotlin.
   3. Set the minimum SDK value to API 19: Android 4.4 (KitKat).

4. Ensure that Google's Maven repository google() is in the list of repositories in the project-level build.gradle file as shown in the following snippet:

   allprojects {
       repositories {
           google()
       }
   }
   

   For more information, see Google's Maven repository.

5. To add the reCAPTCHA Enterprise API dependency, add the following build rule to the dependencies section of your app-level build.gradle file.

     implementation 'com.google.android.recaptcha:recaptcha:18.3.0'
   

   For more information about adding dependencies in Android apps, see Add build dependencies.

6. Add internet permission between the first <manifest> tag and the first <application> tag in your application's manifest (for example, AndroidManifest.xml). This permission is required because the reCAPTCHA Enterprise API involves network operations.

   <manifest ...>
   
       <uses-permission android:name="android.permission.INTERNET" />
   
       <application ...>
       ...
     </application>
   </manifest>
   

7. If you want to use AndroidX libraries in your new project, compile the SDK to Android 9.0 or higher and add the following code snippet to your gradle.properties.

   android.useAndroidX=true
   android.enableJetifier=true
   

   For more information, see Migrating to AndroidX.

Flutter

For detailed instructions about using reCAPTCHA Enterprise through Flutter, see the Flutter documentation.

ReactNative

For detailed instructions about using reCAPTCHA Enterprise through React Native, see the React Native documentation.

Integrate reCAPTCHA Enterprise with your Android app

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

   Note: You must use the reCAPTCHA Enterprise client only once during the lifetime of your app.

   Kotlin

   class MainActivity : AppCompatActivity() {
   
       private lateinit var recaptchaClient: RecaptchaClient
   
       override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
         setContentView(R.layout.activity_main)
         initializeRecaptchaClient()
         // ... rest of onCreate code
       }
   
       private fun initializeRecaptchaClient() {
         lifecycleScope.launch {
           Recaptcha.getClient(application, "KEY_ID")
             .onSuccess { client ->
               recaptchaClient = client
             }
             .onFailure { exception ->
               // Handle communication errors ...
               // See "Handle communication errors" section
             }
         }
       }
   
       // ... rest of activity code.
   }
   

   Java

   public final class MainActivity extends Activity {
     @Nullable private RecaptchaTasksClient recaptchaTasksClient = null;
   
     @Override
     protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       setContentView(R.layout.activity_main);
       initializeRecaptchaClient();
       // ... rest of onCreate code
     }
   
     private void initializeRecaptchaClient() {
       Recaptcha
         .getTasksClient(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 communication errors ...
                 // See "Handle communication errors" section
               }
             });
     }
   
     // ... rest of activity code.
   }
   

   Note: If the API passes an instance of ApiException into onFailure(), you must handle each possible status code that you can retrieve using getStatusCode(). For more information, see Handling communication errors.

2. For each action of your app that is protected using reCAPTCHA Enterprise, call the execute method passing a RecaptchaAction. reCAPTCHA Enterprise 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 communication errors ...
           // See "Handle communication errors" section
         }
     }
   }
   

   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 communication errors ...
               // See "Handle communication errors" section
             }
           });
   }
   

The following sample code snippet shows a full integration of getClient(), and execute() methods on a single Activity app:

Kotlin

class MainActivity : AppCompatActivity() {

  private lateinit var recaptchaClient: RecaptchaClient

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)
    initializeRecaptchaClient()
    findViewById<View>(R.id.btn_login).setOnClickListener { executeLoginAction() }
    findViewById<View>(R.id.btn_redeem).setOnClickListener { executeRedeemAction() }
  }

  private fun initializeRecaptchaClient() {
    lifecycleScope.launch {
      Recaptcha.getClient(application, "KEY_ID")
        .onSuccess { client ->
          recaptchaClient = client
        }
        .onFailure { exception ->
          // Handle communication errors ...
          // See "Handle communication errors" section
        }
    }
  }

  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 communication errors ...
          // See "Handle communication errors" section
        }
    }
  }

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

Java

public final class MainActivity extends Activity {
  @Nullable private RecaptchaTasksClient recaptchaTasksClient = null;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    initializeRecaptchaClient();
    findViewById(R.id.btn_login).setOnClickListener(this::executeLoginAction);
    findViewById(R.id.btn_redeem).setOnClickListener(this::executeRedeemAction);
  }

  private void initializeRecaptchaClient() {
    Recaptcha
      .getTasksClient(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 communication errors ...
              // See "Handle communication errors" section
            }
          });
  }

  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 communication errors ...
              // See "Handle communication errors" section
            }
          });
  }

  private void executeRedeemAction(View v) {
    assert recaptchaTasksClient != null;
    recaptchaTasksClient
      .executeTask(RecaptchaAction.custom("redeem"))
      .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 communication errors ...
              // See "Handle communication errors" section
            }
          });
  }
}

Caution: getClient() and execute() can take several seconds to complete on a device. Therefore, we recommend that you do the following:

• Initialize the client when the app starts. For example, in the onCreate() call of a custom Application class.
• Ensure that execute() calls do not block a UI event. Integrating execute() on your app should not block a UI event, such as pressing a button. For instance, you can call execute() asynchronously when creating a view.

Note: Google Play Store requires you to fill out the Google Play's data safety form before uploading your app to the Play Store. Review Google Play's data disclosure requirements to find the information you need about reCAPTCHA Enterprise Android SDK to fill out the data safety form.

Set a timeout for API calls

You can specify a timeout value for getClient and execute APIs by using the timeout property of each API.

A default timeout of 10 seconds is used for getClient and of 5 seconds for execute APIs.

Kotlin

• Set timeout when calling getClient.

      lifecycleScope.launch {
        Recaptcha.getClient(application, "KEY_ID", timeout = 20000L)
          .onSuccess { client ->
            recaptchaClient = client
          }
          .onFailure { exception ->
            // Handle communication errors ...
            // See "Handle communication errors" section
          }
      }
  

  This code snippet sets the timeout of getClient to 20 seconds.

• Set timeout when calling execute.

      lifecycleScope.launch {
        recaptchaClient
          .execute(RecaptchaAction.LOGIN(), timeout = 10000L)
          .onSuccess { token ->
            // Handle success ...
            // See "What's next" section for instructions
            // about handling tokens.
          }
          .onFailure { exception ->
            // Handle communication errors ...
            // See "Handle communication errors" section
          }
      }
  

  This code snippet sets the timeout of execute to 10 seconds.

Java

• Set timeout when calling getClient.

    Recaptcha
      .getTasksClient(getApplication(), "KEY_ID", 20000L)
      .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 communication errors ...
              // See "Handle communication errors" section
            }
          });
  

  This code snippet sets the timeout of getClient to 20 seconds.

• Set timeout when calling execute.

    recaptchaTasksClient
      .executeTask(RecaptchaAction.custom("redeem"), 10000L)
      .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 communication errors ...
              // See "Handle communication errors" section
            }
          });
  

  This code snippet sets the timeout of execute to 10 seconds.

Handle communication 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.

• To provide feedback on the accuracy of the created assessment, annotate an assessment.

  Note: reCAPTCHA response tokens are assessed and annotated from your backend server, not from the mobile device.