Integra reCAPTCHA Enterprise con le app per Android

Questa pagina spiega come integrare reCAPTCHA Enterprise nella tua app per Android. A causa della variazione dei 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 a più livelli, ad esempio un flusso MFA, per fornire un percorso di utilizzo alternativo per il traffico sospetto.

Importante: l'SDK utilizza il codice dinamico e il riflesso per consentire la modifica e il perfezionamento del sistema di rilevamento nelle applicazioni/SDK di cui è già stato eseguito il deployment. L'insieme delle classi disponibili nel sistema è limitato a un elenco controllato per evitare interferenze con l'applicazione.

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 dell'app Android.

prepara l'ambiente

Avviso: non eseguire la migrazione all'SDK Android 18.2.0 perché l'app potrebbe non funzionare a causa di alcuni errori interni. Per evitare questi problemi, esegui la migrazione direttamente all'SDK Android 18.2.1 o versioni successive. Per maggiori dettagli, consulta il report sui problemi relativo a GitHub.

1. Prepara l'ambiente di sviluppo scaricando e installando la versione più recente 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 vuoi creare una nuova app per dispositivi mobili, avvia un nuovo progetto di Android Studio.

   1. Seleziona Attività vuota. Se vuoi utilizzare Jetpack Compose nella tua app, scegli Empty Compose Activity (Vuota l'attività di scrittura).
   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.2.1'
   

   Per ulteriori informazioni sull'aggiunta di dipendenze nelle app per Android, consulta la pagina Aggiungere dipendenze dalla build.

6. Aggiungi l'autorizzazione Internet tra il primo tag <manifest> e il primo tag <application> nel file manifest dell'applicazione (ad esempio AndroidManifest.xml). Questa autorizzazione è necessaria perché l'API reCAPTCHA Enterprise prevede 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 a gradle.properties.

   android.useAndroidX=true
   android.enableJetifier=true
   

   Per ulteriori informazioni, consulta la pagina Migrazione ad AndroidX.

Integra reCAPTCHA Enterprise con la tua app Android

1. Creare un'istanza di un client utilizzando il SITE_KEY che hai creato per l'app per Android.

   Nota: devi utilizzare il client reCAPTCHA Enterprise solo una volta durante la durata della tua app.

   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.
   }
   

   Nota: se l'API passa un'istanza di ApiException in onFailure(), devi gestire ogni possibile codice di stato che puoi recuperare utilizzando getStatusCode(). Per ulteriori informazioni, consulta la pagina Gestire gli errori di comunicazione.

2. Per ogni azione dell'app protetta tramite reCAPTCHA Enterprise, chiama il metodo execute, che trasmette un'azione RecaptchaAction.re reCAPTCHA Enterprise fornisce un insieme di azioni integrato 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 campione mostra un'integrazione completa di getClient() e metodi execute() in una singola 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
            }
          });
  }
}

Attenzione: getClient() e execute() possono richiedere diversi secondi per essere completati su un dispositivo. Ti consigliamo quindi di procedere come segue:

• Inizializza il client all'avvio dell'app. Ad esempio, nella chiamata onCreate() di una classe Application personalizzata.
• Assicurati che le chiamate execute() non blocchino un evento UI. L'integrazione di execute() nella tua app non deve bloccare un evento UI, come la pressione di un pulsante. Ad esempio, puoi chiamare execute() in modo asincrono durante la creazione di una vista.

Nota: prima di caricare la tua app sul Play Store, il Google Play Store richiede la compilazione del modulo Sicurezza dei dati di Google Play. Leggi i requisiti per la divulgazione dei dati di Google Play per trovare le informazioni necessarie sull'SDK Android per reCAPTCHA Enterprise per compilare il modulo Sicurezza dei dati.

Gestire gli errori di comunicazione

Se la tua app non può comunicare con il servizio reCAPTCHA, è possibile che si sia verificato un errore nell'API. Per gestire correttamente questi errori, devi aggiungere la 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 feedback sull'accuratezza del test creato, annota un test.

  Nota: i token di risposta reCAPTCHA vengono valutati e annotati dal server di backend, non dal dispositivo mobile.