Integrare reCAPTCHA con le app per Android

Questa pagina spiega come integrare reCAPTCHA nella tua app per Android.

L'SDK utilizza la reflection e il codice dinamico per consentire la modifica e il perfezionamento del sistema di rilevamento nelle applicazioni/SDK esistenti. L'insieme di classi disponibili nel sistema è limitato a un elenco controllato per evitare interferenze con l'applicazione.

Prima di iniziare

1. Prepara l'ambiente per reCAPTCHA.

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

   In alternativa, puoi copiare l'ID di una chiave reCAPTCHA esistente per Android eseguendo uno dei seguenti passaggi:

   • Per copiare l'ID di una chiave esistente dalla consoleGoogle Cloud , segui questi passaggi:

     1. Vai alla pagina reCAPTCHA.

        Vai a reCAPTCHA

     2. Nell'elenco delle chiavi reCAPTCHA, tieni il puntatore del mouse sulla chiave che vuoi copiare e poi fai clic su content_copy .
   • Per copiare l'ID di una chiave esistente utilizzando l'API REST, utilizza il metodo projects.keys.list.
   • Per copiare l'ID di una chiave esistente utilizzando gcloud CLI, utilizza il comando gcloud recaptcha keys list.

Preparare l'ambiente Android

Integra reCAPTCHA con la tua app per Android

1. Crea un'istanza di un client utilizzando la chiave reCAPTCHA (KEY_ID) che hai creato per la tua app per Android.

   Kotlin con fetchClient

   Il metodo fetchClient restituisce immediatamente un client e inizia a inizializzare l'SDK in background. Riprova la comunicazione con il server reCAPTCHA in caso di errori di rete.

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

   L'inizializzazione dell'SDK può richiedere diversi secondi. Per ridurre questa latenza, inizializza il client il prima possibile, ad esempio durante la chiamata onCreate() di una classe Application personalizzata. Non devi bloccare gli elementi UI nell'SDK reCAPTCHA.

2. Per ogni azione della tua app protetta tramite reCAPTCHA, chiama il metodo execute passando un RecaptchaAction. reCAPTCHA 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() {
     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 ...
             }
           });
   }
   

Esegui la migrazione dal metodo getClient al metodo fetchClient

Il metodo fetchClient restituisce un RecaptchaClient che riprova l'inizializzazione in caso di errori di rete. Se l'app non ha accesso alla rete quando viene creato il client, quest'ultimo continua a riprovare e viene inizializzato correttamente quando viene acquisita una rete.

Se chiami execute(timeout) e il client non è ancora pronto, tenta di inizializzare prima di restituire un token o un RecaptchaErrorCode.

L'esempio seguente mostra come eseguire la migrazione da 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 ...
            }
          });
  }

Impostare un timeout per le chiamate API

Puoi specificare un valore di timeout per le API execute utilizzando la proprietà withTimeout.

Gestisci gli errori

Se la tua app non riesce a comunicare correttamente con il servizio reCAPTCHA, il problema potrebbe essere dovuto a un errore dell'API. Devi aggiungere la logica nella tua app per gestire correttamente questi errori.

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.