Intégrer reCAPTCHA aux applications Android

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

Si vous souhaitez proposer des tests d'authentification visuels en cas de trafic suspect, vous pouvez utiliser l'API SafetyNet reCAPTCHA.

Important :Le SDK utilise la réflexion et le code dynamique pour permettre la modification et l'affinement du système de détection dans les applications/SDK déjà 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 étapes suivantes:

   • Pour copier l'ID d'une clé existante à partir de la console Google 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 .
   • 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, exécutez la commande gcloud recaptcha keys list.

Préparer votre environnement Android

Avertissement :Ne migrez pas vers le SDK Android 18.2.0, car cela pourrait rendre votre application non fonctionnelle en raison de certaines erreurs internes. Pour éviter ces problèmes, migrez directement vers le SDK Android 18.2.1 ou version ultérieure. Pour en savoir plus, consultez le rapport de problème sur GitHub.

Appareil Android natif

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

2. Assurez-vous de disposer d'une application dont la valeur minimale pour le SDK Android est définie sur API 19: Android 4.4 (KitKat). Vous pouvez définir le SDK minimal de votre application sur l'API 19 ou créer une application mobile.

3. Si vous créez une application mobile, créez une application de test en démarrant un nouveau projet Android Studio:

   1. Sélectionnez Empty Activity (Activité vide). Si vous souhaitez utiliser Jetpack Compose sur votre application, sélectionnez Empty Compose Activity (Activité Compose vide).
   2. Définissez la langue sur kotlin.
   3. Définissez la valeur minimale du SDK sur API 19: Android 4.4 (KitKat).

4. 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 de code suivant:

   allprojects {
       repositories {
           google()
       }
   }
   

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

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

     implementation 'com.google.android.recaptcha:recaptcha:18.5.1'
   

   Pour en savoir plus sur l'ajout de dépendances dans les applications Android, consultez Ajouter des dépendances de compilation.

6. Ajoutez une autorisation Internet entre la première balise <manifest> et la première balise <application> dans le fichier manifeste de votre application (par exemple, AndroidManifest.xml). Cette autorisation est nécessaire, car l'API reCAPTCHA implique des opérations réseau.

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

7. 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 Migrer vers AndroidX.

Flutter

Pour obtenir des instructions détaillées sur l'utilisation de reCAPTCHA via Flutter, consultez la documentation de Flutter.

ReactNative

Pour obtenir des instructions détaillées sur l'utilisation de reCAPTCHA via React Native, consultez la documentation de React Native.

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.

   Remarque :Vous ne devez utiliser le client reCAPTCHA qu'une seule fois pendant la durée de vie de votre application.

   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, "KEY_ID")
             .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(), "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 communication errors ...
                 // See "Handle communication errors" section
               }
             });
     }
   
     // ... rest of activity code.
   }
   

   Remarque :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 Gérer les erreurs de communication.

2. Pour chaque action de votre application protégée à l'aide de reCAPTCHA, appelez la méthode execute en transmettant une RecaptchaAction. reCAPTCHA fournit un ensemble intégré d'actions et, 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() {
     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
             }
           });
   }
   

L'exemple d'extrait de code suivant montre une intégration complète des méthodes getClient() et execute() dans une seule application Activity:

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, "KEY_ID")
        .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(), "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 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
            }
          });
  }
}

Attention: getClient() et execute() peuvent prendre plusieurs secondes sur un appareil. Par conséquent, nous vous recommandons d'effectuer les opérations suivantes :

• Initialisez le client au démarrage de l'application. (par exemple, dans l'appel onCreate() d'une classe Application personnalisée).
• Assurez-vous que les appels execute() ne bloquent pas un événement d'UI. L'intégration de execute() à votre application ne doit pas bloquer un événement d'interface utilisateur, tel qu'un appui sur un bouton. Par exemple, vous pouvez appeler execute() de manière asynchrone lors de la création d'une vue.

Remarque :Sur le Google Play Store, vous devez remplir le formulaire Sécurité des données de Google Play avant d'importer votre application sur le Play Store. Consultez les exigences de divulgation des données de Google Play afin d'obtenir les informations dont vous avez besoin sur le SDK reCAPTCHA pour Android afin de remplir le formulaire Sécurité des données.

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

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

Un délai avant expiration par défaut de 10 secondes est utilisé pour getClient et de 10 secondes pour les API execute.

Kotlin

• Définissez un délai avant expiration lors de l'appel de getClient.

      lifecycleScope.launch {
        Recaptcha.getClient(application, "KEY_ID", timeout = 20000L)
          .onSuccess { client ->
            recaptchaClient = client
          }
          .onFailure { exception ->
            // Handle communication errors ...
            // See "Handle communication errors" section
          }
      }
  

  Cet extrait de code définit le délai avant expiration de getClient sur 20 secondes.

• Définissez un délai avant expiration lors de l'appel de execute.

      lifecycleScope.launch {
        recaptchaClient
          .execute(RecaptchaAction.LOGIN(), timeout = 10000L)
          .onSuccess { token ->
            // Handle success ...
            // See "What's next" section for instructions
            // about handling tokens.
          }
          .onFailure { exception ->
            // Handle communication errors ...
            // See "Handle communication errors" section
          }
      }
  

  Cet extrait de code définit le délai avant expiration de execute sur 10 secondes.

Java

• Définissez un délai avant expiration lors de l'appel de getClient.

    Recaptcha
      .getTasksClient(getApplication(), "KEY_ID", 20000L)
      .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
            }
          });
  

  Cet extrait de code définit le délai avant expiration de getClient sur 20 secondes.

• Définissez un délai avant expiration lors de l'appel de execute.

    recaptchaTasksClient
      .executeTask(RecaptchaAction.custom("redeem"), 10000L)
      .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
            }
          });
  

  Cet extrait de code définit le délai avant expiration de execute sur 10 secondes.

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 d'API courantes, 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 com.google.android.recaptcha.

Étapes suivantes

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

  Remarque :Les jetons de réponse reCAPTCHA sont évalués et annotés à partir de votre serveur backend, et non de l'appareil mobile.