SafetyNet reCAPTCHA API

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

reCAPTCHA ist ein kostenloser Dienst, der mithilfe einer erweiterten Risikoanalyse-Engine Ihre App vor Spam und anderen missbräuchlichen Handlungen schützt. Wenn der Dienst vermutet, dass es sich beim Nutzer, der mit Ihrer App interagiert, um einen Bot handelt, wird ein CAPTCHA angezeigt, 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.

Zusätzliche Nutzungsbedingungen

Durch den Zugriff auf oder die Verwendung der reCAPTCHA API stimmen Sie den Nutzungsbedingungen für Google APIs und 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 Registrierungswebsite für reCAPTCHA 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 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 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 Ihre öffentlichen und privaten Schlüssel unter Websiteschlüssel bzw. Secret-Schlüssel angezeigt. Sie verwenden den Websiteschlüssel, wenn Sie die Bestätigungsanfrage senden, und den Secret-Schlüssel, wenn Sie das Nutzerantworttoken validieren.

SafetyNet API-Abhängigkeit hinzufügen

Bevor Sie die reCAPTCHA API verwenden können, müssen Sie Ihrem Projekt die SafetyNet API 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 Nutzerantworttoken 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:

• Geben Sie Ihren API-Websiteschlüssel als Parameter an.
• Überschreiben Sie die Methoden onSuccess() und onFailure(), 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 prüfen

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 jedoch weiterhin über Ihren Backend-Server validieren.

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