Integrar reCAPTCHA Enterprise a apps para Android

En esta página, se explica cómo integrar reCAPTCHA Enterprise en tu app para Android. Debido a la variación en los dispositivos móviles en términos de tamaño, rendimiento y IU de las apps, el desafío visual de reCAPTCHA (I' m no es un robot) no está disponible para apps para dispositivos móviles. Para obtener un método de fricción alternativo, consulta Cómo configurar 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 función.

  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 a fin de preparar tu entorno de desarrollo.

Cómo integrar reCAPTCHA Enterprise a tu app para Android

Para integrar reCAPTCHA Enterprise con 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, configura el lenguaje como Java y configura el SDK mínimo como API 16: Android 4.1 (Jelly Bean).

  2. Asegúrate de que el repositorio Maven de Google google() esté en la lista de repositorios del archivo build.gradle de 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 del archivo build.gradle de 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 apps para Android, consulta Cómo configurar los Servicios de Google Play.

  4. 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>
    
  5. Si quieres usar bibliotecas AndroidX en tu nuevo proyecto, compila el SDK para 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 llamando a los métodos init(), execute() y close() en la siguiente secuencia:

    1. Llama a init() cuando inicies tu app o la actividad que contenga la acción que quieres proteger.
    2. Llama a execute() después de que se realice la acción que quieres proteger. Por ejemplo, se hace clic en el botón de acceso. Luego, execute() muestra un token RecaptchaResults.
    3. Llama al 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 ambos resultados posibles de las llamadas a la API. En particular, si la API pasa una instancia de ApiException a onFailure(), debes administrar cada código de estado posible que puedas recuperar con 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 muestra 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 instruction
                   // 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 tu app no puede comunicarse con el servicio de reCAPTCHA correctamente, podría deberse a que la API detectó un error. Debes agregar lógica en tu app para manejar correctamente estos errores.

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

Referencia de API

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

¿Qué sigue?