Integra reCAPTCHA Enterprise en apps para Android

En esta página, se explica cómo integrar reCAPTCHA Enterprise en tu app para Android. Debido a la variación de los dispositivos móviles en términos de tamaño de pantalla, rendimiento y IU de las apps, el desafío de la casilla de verificación visual reCAPTCHA (No soy un robot) no está disponible en apps para dispositivos móviles. En cambio, puedes implementar tu propia estrategia de aplicación por niveles, como un flujo de MFA, a fin de proporcionar una ruta de canje alternativa para el tráfico sospechoso.

Importante: El SDK usa reflexión y código dinámico para permitir la modificación y el perfeccionamiento del sistema de detección en los SDK o aplicaciones existentes implementados. El conjunto de clases disponibles en el sistema se restringen a una lista controlada para evitar interferencias con la aplicación.

Antes de comenzar

1. Elige el mejor método para configurar reCAPTCHA Enterprise en tu entorno y completa la configuración.

2. Crea una clave de reCAPTCHA para la plataforma de apps para Android.

Prepare el entorno

Advertencia: No migres al SDK de Android 18.2.0, ya que podría hacer que tu app no funcione debido a errores internos. Para evitar estos problemas, migra directamente al SDK de Android 18.2.1 o versiones posteriores. Para obtener más información, consulta el informe de problemas en GitHub.

1. Descarga e instala la versión más reciente de Android Studio para preparar tu entorno de desarrollo.

2. Asegúrate de tener una app con el valor mínimo del SDK de Android configurado en API 19:Android 4.4 (KitKat). Puedes establecer el SDK mínimo de tu app en el nivel de API 19 o crear una nueva app para dispositivos móviles.

3. Si quieres crear una app para dispositivos móviles nueva, inicia un nuevo proyecto de Android Studio a fin de crear una aplicación de prueba:

   1. Selecciona Actividad vacía. Si quieres usar Jetpack Compose en tu app, elige Empty Compose Activity.
   2. Configura el lenguaje en kotlin.
   3. Establece el valor mínimo del SDK en API 19: Android 4.4 (KitKat).

4. Asegúrate de que el repositorio Maven de Google google() esté en la lista de repositorios del archivo build.gradle a nivel de proyecto, como se muestra en el siguiente fragmento:

   allprojects {
       repositories {
           google()
       }
   }
   

   Para obtener más información, consulta el repositorio de Maven de Google.

5. Para agregar la dependencia de la API de reCAPTCHA Enterprise, agrega la siguiente regla de compilación a la sección dependencies del archivo build.gradle a nivel de la app.

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

   Si quieres obtener más información para agregar dependencias en apps para Android, consulta Cómo agregar dependencias de compilación.

6. Agrega el permiso de Internet entre la primera etiqueta <manifest> y la primera etiqueta <application> en el manifiesto de tu aplicación (por ejemplo, AndroidManifest.xml). Este permiso es obligatorio porque la API de reCAPTCHA Enterprise involucra operaciones de red.

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

7. Si deseas usar bibliotecas AndroidX en tu nuevo proyecto, compila el SDK en Android 9.0 o una versión posterior y agrega el siguiente fragmento de código a gradle.properties.

   android.useAndroidX=true
   android.enableJetifier=true
   

   Para obtener más información, consulta Cómo migrar a AndroidX.

Integra reCAPTCHA Enterprise en tu app para Android

1. Crea una instancia de un cliente mediante el SITE_KEY que creaste para tu app para Android.

   Nota: Debes usar el cliente de reCAPTCHA Enterprise solo una vez durante el ciclo de vida de la 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, "YOUR_SITE_KEY")
             .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(), "YOUR_SITE_KEY")
         .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.
   }
   

   Nota: Si la API pasa una instancia de ApiException a onFailure(), debes controlar cada código de estado posible que puedes recuperar mediante getStatusCode(). Para obtener más información, consulta Cómo controlar los errores de comunicación.

2. Por cada acción de tu app que esté protegida con reCAPTCHA Enterprise, llama al método execute pasando una RecaptchaAction. reCAPTCHA Enterprise proporciona un conjunto integrado de acciones y, si es necesario, puedes crear acciones personalizadas.

   En el siguiente fragmento de código, se muestra cómo usar execute para proteger una acción de LOGIN.

   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
             }
           });
   }
   

En el siguiente fragmento de código de muestra, se muestra una integración completa de los métodos getClient() y execute() en una sola app de actividad:

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, "YOUR_SITE_KEY")
        .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(), "YOUR_SITE_KEY")
      .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
            }
          });
  }
}

Precaución: getClient() y execute() pueden tardar varios segundos en completarse en un dispositivo. Por lo tanto, te recomendamos que hagas lo siguiente:

• Inicializa el cliente cuando se inicia la app. Por ejemplo, en la llamada onCreate() de una clase Application personalizada.
• Asegúrate de que las llamadas a execute() no bloqueen un evento de la IU. La integración de execute() en tu app no debería bloquear un evento de la IU, como presionar un botón. Por ejemplo, puedes llamar a execute() de forma asíncrona cuando creas una vista.

Nota: Google Play Store requiere que completes el formulario de seguridad de los datos de Google Play antes de subir la app a Play Store. Revisa los requisitos de divulgación de datos de Google Play a fin de encontrar la información que necesitas sobre el SDK de reCAPTCHA Enterprise para Android a fin de completar el formulario de seguridad de los datos.

Maneja errores de comunicación

Si la app no puede comunicarse con el servicio de reCAPTCHA correctamente, es posible que la API haya detectado un error. Debes agregar lógica en tu app para controlar correctamente esos errores.

Para obtener más detalles sobre las mitigaciones de errores comunes de la API, consulta RecaptchaErrorCode.

Referencia de API

Si deseas obtener una referencia completa de la API de reCAPTCHA para Android, consulta com.google.android.recaptcha.

¿Qué sigue?

• Para evaluar el token de respuesta de reCAPTCHA, crea una evaluación.

• Para proporcionar comentarios sobre la exactitud de la evaluación creada, anota una evaluación.

  Nota: Los tokens de respuesta de reCAPTCHA se evalúan y anotan desde el servidor de backend, no desde el dispositivo móvil.