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 beim Nutzer, der mit Ihrer App interagiert, um einen Bot und nicht um eine Person handelt, wird ein CAPTCHA angezeigt, das eine Person lösen muss, bevor die 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 oder die Verwendung der reCAPTCHA API stimmen Sie den Nutzungsbedingungen für Google APIs und den folgenden Nutzungsbedingungen für reCAPTCHA zu. Lesen Sie sich alle geltenden Bedingungen 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 Android-Registrierungsseite 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 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 eingegebene Paketname genau mit dem Paketnamen der App übereinstimmen. Geben Sie jeden Paketnamen in einer eigenen Zeile ein.
   • Inhaber:Fügen Sie eine E-Mail-Adresse für jede Person in Ihrer Organisation hinzu, die die reCAPTCHA-Bewertungen Ihrer App überwacht.

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 nächsten Seite werden Ihr öffentlicher und Ihr privater Schlüssel unter Websiteschlüssel bzw. Geheimer Schlüssel angezeigt. Sie verwenden den Websiteschlüssel, wenn Sie die Bestätigungsanfrage senden, und den geheimen Schlüssel, wenn Sie das Antworttoken des Nutzers validieren.

SafetyNet API-Abhängigkeit hinzufügen

Bevor Sie die reCAPTCHA API verwenden, fügen Sie die SafetyNet API Ihrem Projekt hinzu. 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 erhalten.

Bestätigungsanfrage senden

Um die SafetyNet reCAPTCHA API aufzurufen, rufen Sie die verifyWithRecaptcha() Methode 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-Websiteschlüssel als Parameter.
• Überschreiben Sie die onSuccess() und onFailure() Methoden, um beide möglichen Ergebnisse der Bestätigungsanfrage 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());
                    }
                }
        });
}

Antworttoken des Nutzers 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 korrekt gelöst hat. Sie müssen das Antworttoken des Nutzers weiterhin auf Ihrem Back-End-Server validieren.

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