Integrar reCAPTCHA en aplicaciones Android

En esta página se explica cómo integrar reCAPTCHA en una aplicación Android.

El SDK usa la reflexión y el código dinámico para permitir la modificación y la optimización del sistema de detección en las aplicaciones o los SDKs desplegados. El conjunto de clases disponibles en el sistema se limita a una lista controlada para evitar interferencias con la aplicación.

Antes de empezar

1. Prepara tu entorno para reCAPTCHA.

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

   También puede copiar el ID de una clave de reCAPTCHA para Android siguiendo uno de estos pasos:

   • Para copiar el ID de una clave ya creada desde la consola deGoogle Cloud , sigue estos pasos:

     1. Ve a la página reCAPTCHA.

        Ir a reCAPTCHA

     2. En la lista de claves de reCAPTCHA, coloca el puntero sobre la clave que quieras copiar y, a continuación, haz clic en content_copy .
   • Para copiar el ID de una clave que ya tengas mediante la API REST, usa el método projects.keys.list.
   • Para copiar el ID de una clave que ya tengas con gcloud CLI, usa el comando gcloud recaptcha keys list.

Preparar el entorno Android

Integrar reCAPTCHA en una aplicación Android

1. Instancia un cliente usando la clave de reCAPTCHA (KEY_ID) que has creado para tu aplicación Android.

   Kotlin con fetchClient

   El método fetchClient devuelve un cliente inmediatamente e inicia la inicialización del SDK en segundo plano. Vuelve a intentar la comunicación con el servidor de reCAPTCHA si se produce un error de red.

   class CustomApplication : Application() {
   
       private lateinit var recaptchaClient: RecaptchaClient
       // we recommend initializing in a ViewModel
       private val recaptchaScope = CoroutineScope(Dispatchers.IO)
   
       override fun onCreate() {
         super.onCreate()
         initializeRecaptchaClient()
       }
   
       private fun initializeRecaptchaClient() {
         recaptchaScope.launch {
           try {
             recaptchaClient = Recaptcha.fetchClient(application, "KEY_ID")
           } catch(e: RecaptchaException) {
             // Handle errors ...
             // See "Handle errors" section
           }
         }
       }
   }
   

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

   La inicialización del SDK puede tardar varios segundos en completarse. Para reducir esta latencia, inicializa el cliente lo antes posible, por ejemplo, durante la llamada onCreate() de una clase Application personalizada. No debes hacer que los elementos de la interfaz de usuario se bloqueen en el SDK de reCAPTCHA.

2. Por cada acción de tu aplicación que esté protegida con reCAPTCHA, llama al método execute y pasa un RecaptchaAction. reCAPTCHA proporciona un conjunto de acciones integradas 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 LOGIN.

   Kotlin

   private fun executeLoginAction() {
     recaptchaScope.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 ...
             }
           });
   }
   

Migrar del método getClient al método fetchClient

El método fetchClient devuelve un RecaptchaClient que vuelve a intentar la inicialización si se produce un fallo en la red. Si la aplicación no tiene acceso a la red cuando se crea el cliente, este sigue intentándolo y se inicializa correctamente cuando se adquiere una red.

Si llamas a execute(timeout) y el cliente aún no está listo, intenta inicializar antes de devolver un token o un RecaptchaErrorCode.

En el siguiente ejemplo se muestra cómo migrar de getClient a fetchClient.

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

 // Migrate to fetchClient
private fun initializeWithFetchClient() {
  recaptchaScope.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 ...
            }
          });
  }

Definir un tiempo de espera para las llamadas a la API

Puedes especificar un valor de tiempo de espera para las APIs execute mediante la propiedad withTimeout.

Gestionar errores

Si tu aplicación no puede comunicarse correctamente con el servicio reCAPTCHA, puede deberse a que la API ha detectado un error. Debes añadir lógica a tu aplicación para gestionar estos errores correctamente.

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

Referencia de la API

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

Siguientes pasos

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