Intégrer reCAPTCHA Enterprise dans des applications Android

Cette page explique comment intégrer reCAPTCHA Enterprise à votre application Android. En raison de la diversité des appareils mobiles en termes de taille d'écran, de performances et d'interface utilisateur des applications, le test visuel reCAPTCHA (Je ne suis pas un robot) n'est pas disponible pour les applications mobiles. Pour découvrir une autre méthode de filtrage, consultez la page Configurer l'authentification multifacteur (MFA).

Avant de commencer

  1. Choisissez la meilleure méthode pour configurer reCAPTCHA Enterprise dans votre environnement et terminez la configuration.

  2. Le SDK reCAPTCHA Enterprise pour Android est accessible après un examen de sécurité. Contactez notre équipe commerciale pour intégrer votre site à cette fonctionnalité.

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

  4. Préparez votre environnement de développement en téléchargeant et en installant la dernière version d'Android Studio.

Intégrer reCAPTCHA Enterprise à votre application Android

Pour intégrer reCAPTCHA Enterprise à votre application Android, procédez comme suit :

  1. Créez une application de test en démarrant un nouveau projet Android Studio. Lors de la création du projet, sélectionnez EmptyActivity (Activité vide), définissez le langage sur Java et définissez le SDK minimal sur API 16: Android 4.1 (Jelly Bean).

  2. Assurez-vous que le dépôt Maven de Google google() figure dans la liste des dépôts du fichier build.gradle au niveau du projet, comme indiqué dans l'extrait suivant :

    allprojects {
    repositories {
        google()
    }
}

    Pour en savoir plus, consultez les informations sur le dépôt Maven de Google.

  3. Pour ajouter la dépendance de l'API reCAPTCHA Enterprise, ajoutez la règle de compilation suivante à la section dependencies du fichier build.gradle au niveau de l'application.

       implementation 'com.google.android.gms:play-services-recaptcha:17.0.1'

    Pour en savoir plus sur les dépendances d'API dans les applications Android, consultez la page Configurer les services Google Play.

  4. Ajoutez une autorisation Internet entre le premier tag <manifest> et le premier tag <application> dans le fichier manifeste de votre application (par exemple, AndroidManifest.xml). Cette autorisation est requise, car l'API reCAPTCHA Enterprise implique des opérations réseau.

    <manifest ...>

    <uses-permission android:name="android.permission.INTERNET" />

    <application ...>
    ...
  </application>
</manifest>

  5. Si vous souhaitez utiliser des bibliothèques AndroidX dans votre nouveau projet, compilez le SDK vers Android 9.0 ou version ultérieure et ajoutez l'extrait de code suivant à votre gradle.properties.

    android.useAndroidX=true
android.enableJetifier=true

    Pour en savoir plus, consultez la section Migrer vers AndroidX.

  6. Dans votre application (MainActivity.java), appelez l'API reCAPTCHA Enterprise en appelant les méthodes init(), execute() et close() dans l'ordre suivant :

    1. Appelez init() lorsque vous démarrez votre application ou l'activité contenant l'action que vous souhaitez protéger.
    2. Appelez execute() après l'action que vous souhaitez protéger. Par exemple, un clic sur le bouton de connexion. execute() renvoie ensuite un jeton RecaptchaResultData.
    3. Appelez close() lorsque vous n'avez plus d'action à valider.

    Lorsque vous appelez ces trois méthodes dans votre application, remplacez les méthodes onSuccess() et onFailure() pour gérer les deux résultats possibles des appels d'API. En particulier, si l'API transmet une instance de ApiException à onFailure(), vous devez gérer chaque code d'état possible que vous pouvez récupérer à l'aide de getStatusCode(). Pour en savoir plus, consultez la section Gérer les erreurs de communication.

L'exemple de code suivant montre comment appeler les méthodes init(), execute() et 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 ...
               }
             }
           });
  }
}

Gérer les erreurs de communication

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 la page RecaptchaStatusCodes.

Document de référence sur les API

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

Étape suivante