API SafetyNet reCAPTCHA

Le service SafetyNet inclut une API reCAPTCHA que vous pouvez utiliser pour protéger votre application contre le trafic malveillant.

reCAPTCHA est un service gratuit qui utilise un moteur d'analyse des risques avancé pour protéger votre application contre le spam et d'autres actions abusives. Si le service soupçonne que l'utilisateur qui interagit avec votre application peut être un bot plutôt qu'un humain, il renvoie un CAPTCHA qu'un humain doit résoudre pour que votre application puisse continuer à s'exécuter.

Ce document explique comment intégrer l'API reCAPTCHA de SafetyNet à votre application.

Conditions d'utilisation supplémentaires

En accédant à l'API reCAPTCHA ou en l'utilisant, vous acceptez les conditions d'utilisation des API Google et les conditions d'utilisation de reCAPTCHA suivantes. Veuillez lire attentivement l'ensemble des conditions d'utilisation et des règles applicables avant d'accéder aux API.

Enregistrer une paire de clés reCAPTCHA

Pour enregistrer une paire de clés à utiliser avec l'API SafetyNet reCAPTCHA, accédez au site d'inscription à reCAPTCHA Android, puis procédez comme suit :

1. Dans le formulaire qui s'affiche, fournissez les informations suivantes :

   • Label (Libellé) : libellé unique de la clé. En général, vous utilisez le nom de votre entreprise ou organisation.
   • reCAPTCHA type (Type de reCAPTCHA) : sélectionnez reCAPTCHA v2, puis reCAPTCHA Android.
   • Packages : indiquez le nom de package de chaque application qui utilise cette clé API. Pour qu'une application utilise l'API, le nom de package que vous saisissez doit correspondre exactement à celui de l'application. Saisissez chaque nom de package sur une ligne distincte.
   • Owners (Propriétaires) : ajoutez une adresse e-mail pour chaque personne de votre organisation qui surveille les évaluations reCAPTCHA de votre application.

2. Cochez la case Accept the reCAPTCHA Terms of Service (Accepter les conditions d'utilisation de reCAPTCHA).

3. Send alerts to owners (Envoyer des alertes aux propriétaires) : cochez cette case si vous souhaitez recevoir des e-mails sur l'API reCAPTCHA, puis cliquez sur Submit (Envoyer).

4. Sur la page qui s'affiche, vos clés publique et privée figurent respectivement sous Site key (Clé de site) et Secret key (Clé secrète). Vous utilisez la clé de site lorsque vous envoyez la requête de validation, et la clé secrète lorsque vous validez le jeton de réponse de l'utilisateur.

Ajouter la dépendance de l'API SafetyNet

Avant d'utiliser l'API reCAPTCHA, ajoutez l'API SafetyNet à votre projet. Si vous utilisez Android Studio, ajoutez cette dépendance à votre fichier Gradle au niveau de l'application. Pour en savoir plus, consultez Configuration de l'API SafetyNet.

Utiliser l'API reCAPTCHA

Cette section explique comment appeler l'API reCAPTCHA pour envoyer une requête de validation CAPTCHA et recevoir le jeton de réponse de l'utilisateur.

Envoyer la requête de validation

Pour appeler l'API SafetyNet reCAPTCHA, vous appelez la méthode verifyWithRecaptcha(). En général, cette méthode correspond à la sélection par l'utilisateur d'un élément d'interface utilisateur, tel qu'un bouton, dans votre activité.

Lorsque vous utilisez la méthode verifyWithRecaptcha() dans votre application, procédez comme suit :

• Transmettez votre clé de site API en tant que paramètre.
• Remplacez les méthodes onSuccess() et onFailure() pour gérer les deux résultats possibles de la tâche de requête de validation. 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().

L'extrait de code suivant montre comment appeler cette méthode :

fun onClick(view: View) {
    SafetyNet.getClient(this).verifyWithRecaptcha(YOUR_API_SITE_KEY)
            .addOnSuccessListener(this as Executor, OnSuccessListener { response ->
                // Indicates communication with reCAPTCHA service was
                // successful.
                val userResponseToken = response.tokenResult
                if (response.tokenResult?.isNotEmpty() == true) {
                    // Validate the user response token using the
                    // reCAPTCHA siteverify API.
                }
            })
            .addOnFailureListener(this as Executor, OnFailureListener { e ->
                if (e is ApiException) {
                    // An error occurred when communicating with the
                    // reCAPTCHA service. Refer to the status code to
                    // handle the error appropriately.
                    Log.d(TAG, "Error: ${CommonStatusCodes.getStatusCodeString(e.statusCode)}")
                } else {
                    // A different, unknown type of error occurred.
                    Log.d(TAG, "Error: ${e.message}")
                }
            })
}

public void onClick(View v) {
    SafetyNet.getClient(this).verifyWithRecaptcha(YOUR_API_SITE_KEY)
        .addOnSuccessListener((Executor) this,
            new OnSuccessListener<SafetyNetApi.RecaptchaTokenResponse>() {
                @Override
                public void onSuccess(SafetyNetApi.RecaptchaTokenResponse response) {
                    // Indicates communication with reCAPTCHA service was
                    // successful.
                    String userResponseToken = response.getTokenResult();
                    if (!userResponseToken.isEmpty()) {
                        // Validate the user response token using the
                        // reCAPTCHA siteverify API.
                    }
                }
        })
        .addOnFailureListener((Executor) this, new OnFailureListener() {
                @Override
                public void onFailure(@NonNull Exception e) {
                    if (e instanceof ApiException) {
                        // An error occurred when communicating with the
                        // reCAPTCHA service. Refer to the status code to
                        // handle the error appropriately.
                        ApiException apiException = (ApiException) e;
                        int statusCode = apiException.getStatusCode();
                        Log.d(TAG, "Error: " + CommonStatusCodes
                                .getStatusCodeString(statusCode));
                    } else {
                        // A different, unknown type of error occurred.
                        Log.d(TAG, "Error: " + e.getMessage());
                    }
                }
        });
}

Valider le jeton de réponse de l'utilisateur

Lorsque l'API reCAPTCHA exécute la méthode onSuccess(), l'utilisateur a réussi le test CAPTCHA. Toutefois, cette méthode indique uniquement que l'utilisateur a résolu le CAPTCHA correctement. Vous devez tout de même valider le jeton de réponse de l'utilisateur à partir de votre serveur backend.

Pour savoir comment valider le jeton de réponse de l'utilisateur, consultez Vérifier la réponse de l'utilisateur.