Intégrer Google Cloud Fraud Defense aux applications Android

Vous pouvez intégrer Google Cloud Fraud Defense aux applications Android pour évaluer l'intégrité des appareils clients et protéger les interactions sensibles des utilisateurs mobiles.

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éployés existants. L'ensemble des classes disponibles dans le système est limité à une liste contrôlée afin d'éviter toute interférence avec l'application.

Important : Prenez note de la règle d'abandon et d'arrêt et prévoyez de mettre à niveau le SDK régulièrement.

Avant de commencer

1. Préparer votre environnement pour Google Cloud Fraud Defense

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 procédant de l'une des manières suivantes :

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

     1. Accédez à la page Google Cloud Fraud Defense.

        Accéder à Google Cloud Fraud Defense

     2. Sélectionnez l'onglet Keys (clés).
     3. Dans la liste des clés reCAPTCHA, recherchez 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, utilisez 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 d'erreur 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 du SDK Android est définie sur API 23 : Android 6.0 (Marshmallow).

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 dans votre application, sélectionnez Empty Compose Activity (Activité Compose vide).
   2. Définissez le langage sur kotlin.
   3. Définissez la valeur minimale du SDK sur API 23 : Android 6.0 (Marshmallow).

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 suivant :

   allprojects {
       repositories {
           google()
       }
   }
   

   Pour en savoir plus, consultez les informations sur 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 du fichier build.gradle au niveau de l'application.

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

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

6. Ajoutez l'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 requise, 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 Flutter.

React Native

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 avec fetchClient

   La méthode fetchClient renvoie immédiatement un client et commence à initialiser le SDK en arrière-plan. Il relance la communication avec le serveur reCAPTCHA en cas de défaillance du réseau.

   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(this@CustomApplication, "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
     public void onCreate() {
       super.onCreate();
       initializeRecaptchaClient();
     }
   
     private void initializeRecaptchaClient() {
       Recaptcha
         .fetchTaskClient(this, "KEY_ID")
         .addOnSuccessListener(
             this,
             new OnSuccessListener<RecaptchaTasksClient>() {
               @Override
               public void onSuccess(RecaptchaTasksClient client) {
                 CustomApplication.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 limiter 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 bloquer les éléments d'interface utilisateur sur le SDK reCAPTCHA.

   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.

2. Pour chaque action de votre application protégée par reCAPTCHA, appelez la méthode execute en transmettant un RecaptchaAction. La bibliothèque 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 ...
             }
           });
   }
   

Remarque : Le Google Play Store vous demande de 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 pour trouver les informations dont vous avez besoin sur le SDK Android reCAPTCHA afin de remplir le formulaire Sécurité des données.

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

La méthode fetchClient renvoie un RecaptchaClient qui relance l'initialisation en cas de défaillance du réseau. Si l'application n'a pas accès au réseau lors de la création du client, celui-ci continue de ré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.

Kotlin

// 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 ...
    }
  }
}

Java

  // 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.

Kotlin

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

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

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

Java

• Définissez le 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 errors ...
              // See "Handle errors" section
            }
          });
  

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

Gérer les erreurs

Si votre application ne parvient pas à communiquer avec le service reCAPTCHA, cela peut être dû à une erreur de l'API. 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.