Integrar reCAPTCHA Enterprise a apps para Android

Esta página explica cómo integrar reCAPTCHA Enterprise en tu aplicación para Android. Debido a la variación en dispositivos móviles en términos de tamaño de pantalla, IU y rendimiento de las aplicaciones, el desafío visual de reCAPTCHA (No soy un robot ) no está disponible para aplicaciones para dispositivos móviles. Para obtener un método de fricción alternativo, consulta Configura la autenticación de varios factores (MFA).

Antes de comenzar

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

  2. Se puede acceder al SDK de Android después de una revisión de seguridad. Comunícate con nuestro equipo de ventas para incorporar tu sitio a esta característica.

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

  4. Descarga y, luego, instala la versión más reciente de Android Studio para preparar tu entorno de desarrollo.

Integra reCAPTCHA Enterprise a tu app para Android

Para integrar reCAPTCHA Enterprise a tu app para Android, haz lo siguiente:

  1. Crea una aplicación de prueba iniciando un nuevo proyecto de Android Studio. Cuando crees el proyecto, selecciona Actividad vacía, establece el lenguaje en Java y establece el SDK mínimo en API 16: Android 4.1 (Jelly Bean).

  2. Asegúrate de que el repositorio google() de Maven de 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 repositorio Maven de Google.

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

       implementation 'com.google.android.gms:play-services-recaptcha:16.0.1'
    

    Para obtener más información sobre las dependencias de la API en las apps para Android, consulta Configura Servicios de Google Play.

  4. Agrega 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 necesario porque la API de reCAPTCHA Enterprise implica operaciones de red.

    <manifest ...>
    
        <uses-permission android:name="android.permission.INTERNET" />
    
        <application ...>
        ...
      </application>
    </manifest>
    
  5. Si deseas usar bibliotecas AndroidX en tu proyecto nuevo, compila el SDK en Android 9.0 o versiones posteriores y agrega el siguiente fragmento de código a tu gradle.properties.

    android.useAndroidX=true
    android.enableJetifier=true
    

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

  6. En tu app (MainActivity.java), invoca la API de reCAPTCHA Enterprise mediante una llamada a los métodos init(), execute() y close() en la siguiente secuencia:

    1. Llama a init() cuando inicies la app o la actividad que contiene la acción que deseas proteger.
    2. Llama a execute() después de que se realice la acción que deseas proteger. Por ejemplo, se hace clic en el botón de acceso. Luego, execute() muestra un token RecaptchaResultData.
    3. Llama a close() cuando no haya más acciones para verificar.

    Cuando llames a estos tres métodos en tu app, anula los métodos onSuccess() y onFailure() para controlar los dos posibles resultados de las llamadas a la API. En particular, 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.

En el siguiente fragmento de código de muestra, se observa cómo invocar los métodos init(), execute() y close():

public final class MainActivity extends Activity {
   private RecaptchaHandle handle;

   @Override
   protected void onCreate(Bundle savedInstanceState) {
     super.onCreate(savedInstanceState);
     setContentView(R.layout.activity_main);

     // Step 1: Call init() once the activity starts.
     Recaptcha.getClient(this)
         .init("YOUR_SITE_KEY")
         .addOnSuccessListener(
             this,
             new OnSuccessListener<RecaptchaHandle>() {
               @Override
               public void onSuccess(RecaptchaHandle handle) {
                 // Handle success ...
                 MainActivity.this.handle = handle;
               }
             })
         .addOnFailureListener(
             this,
             new OnFailureListener() {
               @Override
               public void onFailure(@NonNull Exception e) {
                 if (e instanceof ApiException) {
                   ApiException apiException = (ApiException) e;
                   Status apiErrorStatus = apiException.getStatusCode();
                   // Handle api errors ...
                 } else {
                   // Handle other failures ...
                 }
               }
             });
   }

   public void onClick(View v) {
     // Step 2: call execute() when there is an action to protect.
     Recaptcha.getClient(this)
         .execute(this.handle, new RecaptchaAction(new RecaptchaActionType(RecaptchaActionType.LOGIN)))
         .addOnSuccessListener(
             this,
             new OnSuccessListener<RecaptchaResultData>() {
               @Override
               public void onSuccess(RecaptchaResultData response) {
                 String token = response.getTokenResult();
                 // Handle success ...
                 if (!token.isEmpty()) {
                   Log.d(TAG, "reCAPTCHA response token: " + token);
                   // Validate the response token by following the instructions
                   // when creating an assessment.
                 }
               }
             })
         .addOnFailureListener(
             this,
             new OnFailureListener() {
               @Override
               public void onFailure(@NonNull Exception e) {
                 if (e instanceof ApiException) {
                   ApiException apiException = (ApiException) e;
                   Status apiErrorStatus = apiException.getStatusCode();
                   // Handle api errors ...
                 } else {
                   // Handle other failures ...
                 }
               }
             });
   }

  @Override
  protected void onDestroy() {
    // Step 3: call close() when there is no more action to verify.
   Recaptcha.getClient(this)
       .close(handle)
       .addOnSuccessListener(
           this,
           new OnSuccessListener<Boolean>() {
             @Override
             public void onSuccess(Boolean gotClosed) {
               // Handle success ...
             }
           })
       .addOnFailureListener(
           this,
           new OnFailureListener() {
             @Override
             public void onFailure(@NonNull Exception e) {
               if (e instanceof ApiException) {
                 ApiException apiException = (ApiException) e;
                 Status apiErrorStatus = apiException.getStatusCode();
                 // Handle api errors ...
               } else {
                 // Handle other failures ...
               }
             }
           });
  }
}

Controla errores de comunicación

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

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

Referencia de API

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

¿Qué sigue?