Integra reCAPTCHA Enterprise con le app Android

Questa pagina spiega come integrare reCAPTCHA Enterprise nella tua app Android. A causa della variazione dei dispositivi mobili in termini di dimensioni dello schermo, prestazioni e UI delle app, la verifica visiva di reCAPTCHA (I'm non è un robot) non è disponibile per le app per dispositivi mobili. Per un metodo di attrito alternativo, consulta Configurare l'autenticazione a più fattori (MFA).

Prima di iniziare

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

  2. L'SDK Android per reCAPTCHA Enterprise è accessibile dopo un controllo di sicurezza. Contatta il nostro team di vendita per l'onboarding del tuo sito per questa funzionalità.

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

  4. Prepara l'ambiente di sviluppo scaricando e installando la versione più recente di Android Studio.

Integra reCAPTCHA Enterprise con la tua app Android

Per integrare reCAPTCHA Enterprise con la tua app Android:

  1. Crea un'applicazione di test avviando un nuovo progetto Android Studio. Quando crei il progetto, seleziona Attività vuota, imposta il linguaggio su Java e imposta l'SDK minimo su API 16: Android 4.1 (Jelly Bean).

  2. Assicurati che il repository Maven di Google nell'elenco 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.

  3. 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.gms:play-services-recaptcha:17.0.1'
    

    Per ulteriori informazioni sulle dipendenze dell'API nelle app Android, consulta la sezione Configurare Google Play Services.

  4. 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 è obbligatoria perché l'API reCAPTCHA Enterprise prevede operazioni di rete.

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

    android.useAndroidX=true
    android.enableJetifier=true
    

    Per ulteriori informazioni, consulta la sezione Migrazione ad AndroidX.

  6. Nella tua app (MainActivity.java), richiama l'API reCAPTCHA Enterprise chiamando i metodi init(), execute() e close() nella seguente sequenza:

    1. Richiama init() quando avvii l'app o l'attività contenente l'azione che vuoi proteggere.
    2. Chiama il numero execute() dopo l'azione che vuoi proteggere. Ad esempio, viene fatto clic sul pulsante di accesso. execute() restituisce quindi un token RecaptchaResultData.
    3. Chiama close() quando non ci sono altre azioni da verificare.

    Quando chiami questi tre metodi nella tua app, sostituisci i metodi onSuccess() e onFailure() per gestire entrambi i possibili risultati delle chiamate API. In particolare, 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 Gestire gli errori di comunicazione.

Il seguente esempio di snippet di codice mostra come richiamare i metodi init(), execute() e 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 instructions
                   // 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 ...
               }
             }
           });
  }
}

Gestire gli errori di comunicazione

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

Per ulteriori informazioni sulle mitigazioni per gli errori comuni delle API, consulta la pagina RecaptchaStatusCodes.

Riferimento API

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

Passaggi successivi