Intégrer reCAPTCHA à des applications Android

Cette page explique comment intégrer reCAPTCHA à votre application Android.

Le SDK utilise la réflexion et le code dynamique pour permettre la modification et l'amélioration du système de détection dans les applications/SDK existants déployés. L'ensemble des classes disponibles dans le système est limité à une liste contrôlée pour éviter toute interférence avec l'application.

Avant de commencer

1. Préparez votre environnement pour reCAPTCHA.

2. Créez une clé reCAPTCHA pour la plate-forme d'applications Android.

   Vous pouvez également copier l'ID d'une clé reCAPTCHA existante pour Android en effectuant l'une des opérations suivantes :

   • Pour copier l'ID d'une clé existante à partir de la consoleGoogle Cloud , procédez comme suit :

     1. Accédez à la page reCAPTCHA.

        Accéder à reCAPTCHA

     2. Dans la liste des clés reCAPTCHA, pointez sur la clé que vous souhaitez copier, puis cliquez sur content_copy .
   • Pour copier l'ID d'une clé existante à l'aide de l'API REST, utilisez la méthode projects.keys.list.
   • Pour copier l'ID d'une clé existante à l'aide de la gcloud CLI, utilisez la commande gcloud recaptcha keys list.

Préparer votre environnement Android

Intégrer reCAPTCHA à votre application Android

1. Instanciez un client à l'aide de la clé reCAPTCHA (KEY_ID) que vous avez créée pour votre application Android.

   Kotlin avec fetchClient

   La méthode fetchClient renvoie immédiatement un client et commence à initialiser le SDK en arrière-plan. En cas d'échec du réseau, il tente à nouveau de communiquer avec le serveur reCAPTCHA.

   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 avec 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'initialisation du SDK peut prendre plusieurs secondes. Pour atténuer cette latence, initialisez le client le plus tôt possible, par exemple lors de l'appel onCreate() d'une classe Application personnalisée. Vous ne devez pas faire en sorte que les éléments d'UI bloquent le SDK reCAPTCHA.

2. Pour chaque action de votre application protégée à l'aide de reCAPTCHA, appelez la méthode execute en transmettant un RecaptchaAction. reCAPTCHA fournit un ensemble d'actions intégrées. Si nécessaire, vous pouvez créer des actions personnalisées.

   L'extrait de code suivant montre comment utiliser execute pour protéger une action 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 ...
             }
           });
   }
   

Migrer de la méthode getClient vers la méthode fetchClient

La méthode fetchClient renvoie un RecaptchaClient qui réessaie l'initialisation en cas d'échec du réseau. Si l'application n'a pas accès au réseau lors de la création du client, celui-ci continue d'essayer et s'initialise correctement lorsqu'un réseau est acquis.

Si vous appelez execute(timeout) et que le client n'est pas encore prêt, il tente de s'initialiser avant de renvoyer un jeton ou un RecaptchaErrorCode.

L'exemple suivant montre comment migrer de getClient vers 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 ...
            }
          });
  }

Définir un délai avant expiration pour les appels d'API

Vous pouvez spécifier une valeur de délai avant expiration pour les API execute à l'aide de la propriété withTimeout.

Gérer les erreurs

Si votre application ne peut pas communiquer avec le service reCAPTCHA, il se peut que l'API ait rencontré une erreur. Vous devez ajouter une logique dans votre application pour gérer correctement ces erreurs.

Pour en savoir plus sur les mesures d'atténuation des erreurs courantes liées aux API, consultez RecaptchaErrorCode.

Documentation de référence de l'API

Pour obtenir une documentation de référence complète sur l'API reCAPTCHA pour Android, consultez la page com.google.android.recaptcha.

Étapes suivantes

• Pour évaluer le jeton de réponse reCAPTCHA, créez une évaluation.