Integra reCAPTCHA Enterprise en apps para Android

Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

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 del tamaño de la pantalla, el rendimiento y las IU de las apps, el desafío de reCAPTCHA (I'm not a robot) no está disponible en las apps para dispositivos móviles. En cambio, puedes implementar tu propia estrategia de aplicación por niveles, como un flujo de MFA, para proporcionar una ruta de canje alternativa para el tráfico sospechoso.

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

  1. Descarga y, luego, 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 de SDK de Android establecido en API 23: Android 6.0 (Marshmallow). Puedes establecer el SDK mínimo de tu app en API 23 o crear una nueva app para dispositivos móviles.

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

    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 de SDK en API 23: Android 6.0 (Marshmallow).
  4. 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 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.0.0'
    

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

  6. 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 obligatorio porque la API de reCAPTCHA Enterprise implica operaciones de red.

    <manifest ...>
    
        <uses-permission android:name="android.permission.INTERNET" />
    
        <application ...>
        ...
      </application>
    </manifest>
    
  7. Si quieres usar bibliotecas AndroidX en tu proyecto nuevo, compila el SDK para Android 9.0 o una versión posterior, 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.

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.

    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.
    }
    
  2. Para cada acción de tu app que esté protegida con reCAPTCHA Enterprise, llama al método execute y pasa 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 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
            }
          });
  }
}

Maneja errores de comunicación

Si tu app no puede comunicarse con el servicio de reCAPTCHA correctamente, puede deberse a un error en la API. Debes agregar lógica a tu app para manejar correctamente esos errores.

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

Referencia de la API

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

¿Qué sigue?