Integra reCAPTCHA Enterprise con le app per Android

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Questa pagina spiega come integrare reCAPTCHA Enterprise nella tua app Android. A causa della variazione nei dispositivi mobili in termini di dimensioni dello schermo, prestazioni e UI delle app, la verifica visiva della casella di controllo reCAPTCHA (Non sono un robot) non è disponibile per le app mobile. Puoi invece implementare la tua strategia di applicazione forzata a più livelli, ad esempio un flusso MFA per fornire un percorso di riscatto alternativo per il traffico sospetto.

Prima di iniziare

  1. Scegli il metodo migliore per configurare reCAPTCHA Enterprise nel tuo ambiente e completa la configurazione.

  2. Crea una chiave reCAPTCHA per la piattaforma app Android.

prepara l'ambiente

  1. Prepara l'ambiente di sviluppo scaricando e installando l'ultima versione di Android Studio.

  2. Assicurati di avere un'app con il valore minimo dell'SDK Android impostato su API 19: Android 4.4 (KitKat). Puoi impostare l'SDK minimo della tua app sull'API 19 o creare una nuova app mobile.

  3. Se stai creando una nuova app mobile, crea un'applicazione di test avviando un nuovo progetto Android Studio:

    1. Seleziona Attività vuota. Se vuoi utilizzare Jetpack Compose nella tua app, scegli Empty Compose Activity (Attività di scrittura vuota).
    2. Imposta la lingua su kotlin.
    3. Imposta il valore minimo dell'SDK su API 19: Android 4.4 (KitKat).
  4. Assicurati che il repository Maven di Google google() sia nell'elenco dei repository nel file build.gradle a livello di progetto, come mostrato nel seguente snippet:

    allprojects {
        repositories {
            google()
        }
    }
    

    Per ulteriori informazioni, consulta il repository Maven di Google.

  5. Per aggiungere la dipendenza dell'API reCAPTCHA Enterprise, aggiungi la seguente regola di compilazione alla sezione dependencies del file build.gradle a livello di app.

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

    Per ulteriori informazioni sull'aggiunta di dipendenze nelle app per Android, consulta Aggiungere le dipendenze della build.

  6. Aggiungi l'autorizzazione Internet tra il primo tag <manifest> e il primo tag <application> nel manifest dell'applicazione (ad esempio, AndroidManifest.xml). Questa autorizzazione è obbligatoria perché l'API reCAPTCHA Enterprise comporta operazioni di rete.

    <manifest ...>
    
        <uses-permission android:name="android.permission.INTERNET" />
    
        <application ...>
        ...
      </application>
    </manifest>
    
  7. Se vuoi utilizzare le librerie AndroidX nel nuovo progetto, compila l'SDK ad Android 9.0 o versioni successive e aggiungi il seguente snippet di codice al tuo codice gradle.properties.

    android.useAndroidX=true
    android.enableJetifier=true
    

    Per maggiori informazioni, consulta la pagina Migrazione ad AndroidX.

Integra reCAPTCHA Enterprise con la tua app per Android

  1. Crea un'istanza di un client utilizzando l'SITE_KEY che hai creato per l'app per 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. Per ogni azione dell'app protetta tramite reCAPTCHA Enterprise, richiama il metodo execute che supera l'azione reCAPTCHA. reCAPTCHA Enterprise fornisce un insieme integrato di azioni e, se necessario, puoi creare azioni personalizzate.

    Il seguente snippet di codice mostra come utilizzare execute per proteggere un'azione 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
              }
            });
    }
    

Il seguente snippet di codice di esempio mostra un'integrazione completa dei metodi getClient() e execute() in un'unica app per le attività:

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

Gestire gli errori di comunicazione

Se la tua app non riesce a comunicare con il servizio reCAPTCHA, è possibile che l'API abbia riscontrato un errore. Per gestire adeguatamente questi errori, devi aggiungere una logica nell'app.

Per maggiori dettagli sulle mitigazioni per gli errori API comuni, consulta RecaptchaErrorCode.

Riferimento API

Per un riferimento completo dell'API reCAPTCHA per Android, consulta com.google.android.recaptcha.

Passaggi successivi

  • Per valutare il token di risposta reCAPTCHA, crea una valutazione.

  • Per fornire un feedback sull'accuratezza del test creato, annota una valutazione.