Diese Seite wurde von der Cloud Translation API übersetzt.

reCAPTCHA in Android-Apps einbinden

Auf dieser Seite wird erläutert, wie Sie reCAPTCHA in Ihre Android-App einbinden.

Wenn Sie bei verdächtigem Traffic visuelle Aufgaben stellen möchten, können Sie die SafetyNet reCAPTCHA API verwenden.

Das SDK verwendet Reflection und dynamischen Code, um das Erkennungssystem in den vorhandenen bereitgestellten Anwendungen/SDKs zu ändern und zu optimieren. Die im System verfügbaren Klassen sind auf eine kontrollierte Liste beschränkt, um Störungen der Anwendung zu vermeiden.

Hinweise

Umgebung für reCAPTCHA vorbereiten
Erstellen Sie einen reCAPTCHA-Schlüssel für die Android-App-Plattform.

Alternativ können Sie die ID eines vorhandenen reCAPTCHA-Schlüssels für Android kopieren. Führen Sie dazu einen der folgenden Schritte aus:
- So kopieren Sie die ID eines vorhandenen Schlüssels aus der Google Cloud Console:
  1. Rufen Sie die Seite reCAPTCHA auf.
    
    Zu reCAPTCHA
  2. Halten Sie in der Liste der reCAPTCHA-Schlüssel den Mauszeiger auf den Schlüssel, den Sie kopieren möchten, und klicken Sie dann auf .
- Verwenden Sie die Methode projects.keys.list, um die ID eines vorhandenen Schlüssels mithilfe der REST API zu kopieren.
- Verwenden Sie den Befehl gcloud recaptcha keys list, um die ID eines vorhandenen Schlüssels mit der gcloud CLI zu kopieren.

Android-Umgebung vorbereiten

Native Android-Anwendung

Um Ihre Entwicklungsumgebung vorzubereiten, laden Sie die neueste Version von Android Studio herunt und installieren sie.
Achten Sie darauf, dass für das Android SDK der Mindestwert API 23: Android 6.0 (Marshmallow) festgelegt ist. Sie können entweder das Minimum SDK Ihrer App auf API 19 festlegen oder eine neue App erstellen.
Wenn Sie eine neue App erstellen, erstellen Sie eine Testanwendung. Dazu starten Sie ein neues Android Studio-Projekt:
1. Wählen Sie Leere Aktivität aus. Wenn Sie Jetpack Compose in Ihrer App verwenden möchten, wählen Sie Leere Compose-Aktivität aus.
2. Legen Sie für die Sprache kotlin fest.
3. Legen Sie den Wert für das Minimum SDK auf API 23: Android 6.0 (Marshmallow) fest.
Sorgen Sie dafür, dass das Maven-Repository google() von Google in der Liste der Repositories in der build.gradle-Datei auf Projektebene enthalten ist, wie im folgenden Snippet gezeigt:
```
allprojects {
    repositories {
        google()
    }
}
```
Weitere Informationen finden Sie im Maven-Repository von Google.
Um die reCAPTCHA API-Abhängigkeit hinzuzufügen, fügen Sie die folgende Build-Regel in den Abschnitt dependencies der build.gradle-Datei auf Anwendungsebene ein.
```
  implementation 'com.google.android.recaptcha:recaptcha:18.7.0-beta01'
```
Weitere Informationen zum Hinzufügen von Abhängigkeiten in Android-Apps finden Sie unter Build-Abhängigkeiten hinzufügen.
Fügen Sie eine Internetberechtigung zwischen dem ersten <manifest>-Tag und dem ersten <application>-Tag im Manifest Ihrer Anwendung hinzu (z. B. AndroidManifest.xml). Diese Berechtigung ist erforderlich, da die reCAPTCHA API Netzwerkvorgänge umfasst.
```
<manifest ...>

    <uses-permission android:name="android.permission.INTERNET" />

    <application ...>
    ...
  </application>
</manifest>
```
Wenn Sie AndroidX-Bibliotheken in Ihrem neuen Projekt verwenden möchten, kompilieren Sie das SDK mit Android 9.0 oder höher und fügen Sie das folgende Code-Snippet in Ihren gradle.properties ein:
```
android.useAndroidX=true
android.enableJetifier=true
```
Weitere Informationen finden Sie unter Zu AndroidX migrieren.

Flutter

Eine ausführliche Anleitung zur Verwendung von reCAPTCHA über Flutter finden Sie in der Flutter-Dokumentation.

React Native

Eine ausführliche Anleitung zur Verwendung von reCAPTCHA über React Native finden Sie in der React Native-Dokumentation.

reCAPTCHA in Ihre Android-App einbinden

Instantiieren Sie einen Client mit dem reCAPTCHA-Schlüssel (KEY_ID), den Sie für Ihre Android-App erstellt haben.

Kotlin mit `fetchClient`

Die fetchClient-Methode gibt sofort einen Client zurück und startet die Initialisierung des SDKs im Hintergrund. Bei Netzwerkausfällen wird die Kommunikation mit dem reCAPTCHA-Server noch einmal versucht.

class CustomApplication : Application() {

    private lateinit var recaptchaClient: RecaptchaClient

    override fun onCreate() {
      super.onCreate()
      initializeRecaptchaClient()
    }

    private fun initializeRecaptchaClient() {
      lifecycleScope.launch {
        try {
          recaptchaClient = Recaptcha.fetchClient(application, "KEY_ID")
        } catch(e: RecaptchaException) {
          // Handle errors ...
          // See "Handle errors" section
        }
      }
    }
}

Java mit `fetchClient`

public final class CustomApplication extends Application {
  @Nullable private RecaptchaTasksClient recaptchaTasksClient = null;

  @Override
  protected void onCreate() {
    super.onCreate();
    initializeRecaptchaClient();
  }

  private void initializeRecaptchaClient() {
    Recaptcha
      .fetchTaskClient(getApplication(), "KEY_ID")
      .addOnSuccessListener(
          this,
          new OnSuccessListener<RecaptchaTasksClient>() {
            @Override
            public void onSuccess(RecaptchaTasksClient client) {
              MainActivity.this.recaptchaTasksClient = client;
            }
          })
      .addOnFailureListener(
          this,
          new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
              // Handle errors ...
              // See "Handle errors" section
            }
          });
  }
}

Die Initialisierung des SDK kann einige Sekunden dauern. Um diese Latenz zu verringern, initialisieren Sie den Client so früh wie möglich, z. B. beim onCreate()-Aufruf einer benutzerdefinierten Application-Klasse. UI-Elemente sollten nicht vom reCAPTCHA SDK blockiert werden.

Rufen Sie für jede Aktion Ihrer App, die mit reCAPTCHA geschützt ist, die Methode execute mit einer RecaptchaAction auf. reCAPTCHA bietet eine Reihe vordefinierter Aktionen. Bei Bedarf können Sie auch benutzerdefinierte Aktionen erstellen.

Das folgende Code-Snippet zeigt, wie eine LOGIN-Aktion mit execute geschützt wird.

Kotlin

private fun executeLoginAction() {
  lifecycleScope.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 ...
          }
        });
}

Von der Methode „getClient“ zur Methode „fetchClient“ migrieren

Die fetchClient-Methode gibt einen RecaptchaClient zurück, der die Initialisierung bei Netzwerkfehlern noch einmal versucht. Wenn die App beim Erstellen des Clients keinen Netzwerkzugriff hat, wird der Client immer wieder neu gestartet und initialisiert, sobald ein Netzwerk gefunden wurde.

Wenn du execute(timeout) aufrufst und der Client noch nicht bereit ist, versucht er, sich zu initialisieren, bevor er ein Token oder einen RecaptchaErrorCode zurückgibt.

Das folgende Beispiel zeigt, wie Sie von getClient zu fetchClient migrieren.

Kotlin

// Migrate from getClient
private fun initializeWithGetClient() {
  lifecycleScope.launch {
    Recaptcha.getClient(application, "KEY_ID")
      .onSuccess { client ->
        recaptchaClient = client
      }
      .onFailure { exception ->
        // Handle errors ...
      }
  }
}

 // Migrate to fetchClient
private fun initializeWithFetchClient() {
  lifecycleScope.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 ...
            }
          });
  }

Zeitlimit für API-Aufrufe festlegen

Mit der Property withTimeout können Sie einen Zeitüberschreitungswert für die execute APIs angeben.

Kotlin

Legen Sie ein Zeitlimit für den Aufruf von execute fest.

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

In diesem Code-Snippet wird das Zeitlimit für execute auf 10 Sekunden festgelegt.

Java

Legen Sie ein Zeitlimit für den Aufruf von execute fest.

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

In diesem Code-Snippet wird das Zeitlimit für execute auf 10 Sekunden festgelegt.

Fehler verarbeiten

Wenn Ihre Anwendung nicht mit dem reCAPTCHA-Dienst kommunizieren kann, ist möglicherweise ein API-Fehler aufgetreten. Sie müssen Ihrer Anwendung eine Logik hinzufügen, um solche Fehler ordnungsgemäß zu bearbeiten.

Weitere Informationen zu den Maßnahmen für die häufigsten API-Fehler finden Sie unter RecaptchaErrorCode.

API-Referenz

Eine vollständige Referenz zur reCAPTCHA API für Android finden Sie unter com.google.android.recaptcha.

Nächste Schritte

Um das reCAPTCHA-Antworttoken zu bewerten, erstellen Sie eine Bewertung.

Hinweis: reCAPTCHA-Antworttokens werden von Ihrem Backendserver und nicht vom Mobilgerät bewertet und kommentiert.

reCAPTCHA in Android-Apps einbinden

Hinweise

Android-Umgebung vorbereiten

Native Android-Anwendung

Flutter

React Native

reCAPTCHA in Ihre Android-App einbinden

Kotlin mit fetchClient

Java mit fetchClient

Kotlin

Java

Von der Methode „getClient“ zur Methode „fetchClient“ migrieren

Kotlin

Java

Zeitlimit für API-Aufrufe festlegen

Kotlin

Java

Fehler verarbeiten

API-Referenz

Nächste Schritte

Kotlin mit `fetchClient`

Java mit `fetchClient`