SafetyNet reCAPTCHA API

Der SafetyNet-Dienst umfasst eine reCAPTCHA API, mit der Sie Ihre App vor schädlichem Traffic schützen können.

reCAPTCHA ist ein kostenloser Dienst, der eine Engine zur erweiterten Risikoanalyse verwendet, um Ihre App vor Spam und anderem Missbrauch zu schützen. Wenn der Dienst vermutet, dass es sich bei dem Nutzer, der mit Ihrer App interagiert, um einen Bot und nicht um einen Menschen handelt, wird ein CAPTCHA eingeblendet, das ein Mensch lösen muss, bevor Ihre App weiter ausgeführt werden kann.

In diesem Dokument wird erläutert, wie Sie die reCAPTCHA API von SafetyNet in Ihre App einbinden.

Zusatzbedingungen

Durch den Zugriff auf die oder die Verwendung der reCAPTCHA API stimmen Sie den Nutzungsbedingungen für Google APIs sowie den folgenden reCAPTCHA-Nutzungsbedingungen zu. Lesen Sie sich alle anwendbaren Nutzungsbedingungen und Richtlinien durch, bevor Sie auf die APIs zugreifen.

reCAPTCHA-Schlüsselpaar registrieren

Wenn Sie ein Schlüsselpaar für die Verwendung mit der SafetyNet reCAPTCHA API registrieren möchten, rufen Sie die reCAPTCHA-Registrierungsseite für Android auf und führen Sie die folgenden Schritte aus:

1. Geben Sie im angezeigten Formular die folgenden Informationen an:

   • Label:Ein eindeutiges Label für Ihren Schlüssel. In der Regel verwenden Sie den Namen Ihres Unternehmens oder Ihrer Organisation.
   • reCAPTCHA-Typ:Wählen Sie reCAPTCHA V2 und dann reCAPTCHA für Android aus.
   • Pakete:Geben Sie den Paketnamen jeder App an, die diesen API-Schlüssel verwendet. Damit eine App die API verwenden kann, muss der von Ihnen eingegebene Paketname genau mit dem Paketnamen der App übereinstimmen. Geben Sie jeden Paketnamen in einer eigenen Zeile ein.
   • Inhaber:Fügen Sie für jede Person in Ihrer Organisation, die die reCAPTCHA-Bewertungen Ihrer App überwacht, eine E-Mail-Adresse hinzu.

2. Klicken Sie das Kästchen Nutzungsbedingungen für reCAPTCHA akzeptieren an.

3. Benachrichtigungen an Inhaber senden:Klicken Sie dieses Kästchen an, wenn Sie E‑Mails zur reCAPTCHA API erhalten möchten, und klicken Sie dann auf Senden.

4. Auf der Seite, die als Nächstes angezeigt wird, sehen Sie Ihren öffentlichen und privaten Schlüssel unter Website-Schlüssel bzw. Geheimer Schlüssel. Sie verwenden den Websiteschlüssel, wenn Sie die Bestätigungsanfrage senden, und den Secret-Schlüssel, wenn Sie das Nutzerantwort-Token validieren.

SafetyNet API-Abhängigkeit hinzufügen

Bevor Sie die reCAPTCHA API verwenden, müssen Sie die SafetyNet API Ihrem Projekt hinzufügen. Wenn Sie Android Studio verwenden, fügen Sie diese Abhängigkeit der Gradle-Datei auf App-Ebene hinzu. Weitere Informationen finden Sie unter SafetyNet API einrichten.

reCAPTCHA API verwenden

In diesem Abschnitt wird beschrieben, wie Sie die reCAPTCHA API aufrufen, um eine CAPTCHA-Bestätigungsanfrage zu senden und das Antworttoken des Nutzers zu empfangen.

Überprüfungsanfrage senden

Zum Aufrufen der SafetyNet reCAPTCHA API rufen Sie die Methode verifyWithRecaptcha() auf. In der Regel entspricht diese Methode dem Nutzer, der ein UI-Element wie eine Schaltfläche in Ihrer Aktivität auswählt.

Wenn Sie die Methode verifyWithRecaptcha() in Ihrer App verwenden, müssen Sie Folgendes tun:

• Übergeben Sie Ihren API-Siteschlüssel als Parameter.
• Überschreiben Sie die Methoden onSuccess() und onFailure(), um beide möglichen Ergebnisse der Aufgabe zur Überprüfungsanfrage zu verarbeiten. Insbesondere dann, wenn die API eine Instanz von ApiException an onFailure() weiterleitet, müssen Sie jeden möglichen Statuscode verarbeiten, den Sie mit getStatusCode() abrufen können.

Das folgende Code-Snippet zeigt, wie diese Methode aufgerufen wird:

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());
                    }
                }
        });
}

Nutzerantwort-Token validieren

Wenn die reCAPTCHA API die Methode onSuccess() ausführt, hat der Nutzer die CAPTCHA-Aufgabe erfolgreich abgeschlossen. Diese Methode gibt jedoch nur an, dass der Nutzer das CAPTCHA richtig gelöst hat. Sie müssen das Antworttoken des Nutzers weiterhin auf Ihrem Backend-Server validieren.

Informationen zum Validieren des Antworttokens des Nutzers finden Sie unter Antwort des Nutzers prüfen.