reCAPTCHA Enterprise in Android-Apps einbinden

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

Wenn Sie für verdächtigen Traffic visuelle Identitätsbestätigungen bereitstellen möchten, können Sie die SafetyNet reCAPTCHA API verwenden.

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

Hinweise

1. Bereiten Sie Ihre Umgebung für reCAPTCHA Enterprise vor.

2. 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 Enterprise auf.

        Zur Seite „reCAPTCHA Enterprise“

     2. Bewegen Sie den Mauszeiger in der Liste der reCAPTCHA-Schlüssel auf den Schlüssel, den Sie kopieren möchten, und klicken Sie dann auf .
   • Wenn Sie die ID eines vorhandenen Schlüssels mithilfe der REST API kopieren möchten, verwenden Sie die Methode projects.keys.list.
   • Wenn Sie die ID eines vorhandenen Schlüssels mithilfe der gcloud CLI kopieren möchten, verwenden Sie den Befehl gcloud reCAPTCHA keys list.

Android-Umgebung vorbereiten

Warnung :Migrieren Sie nicht zum Android SDK 18.2.0, da Ihre App dann aufgrund interner Fehler möglicherweise nicht mehr funktioniert. Migrieren Sie direkt zu Android SDK 18.2.1 oder höher, um diese Probleme zu vermeiden. Weitere Informationen findest du im Problembericht auf GitHub.

Native Android-Anwendung

1. Um Ihre Entwicklungsumgebung vorzubereiten, laden Sie die neueste Version von Android Studio herunt und installieren sie.

2. Prüfen Sie, ob Sie eine App haben, bei der der Mindestwert für das Android SDK auf API 19: Android 4.4 (KitKat) festgelegt ist. Sie können entweder die SDK-Mindestversion Ihrer App auf API 19 festlegen oder eine neue mobile App erstellen.

3. Wenn Sie eine neue mobile App erstellen, erstellen Sie eine Test-App, indem Sie ein neues Android Studio-Projekt starten:

   1. Wählen Sie Empty Activity (Leere Aktivität) aus. Wenn Sie Jetpack Compose für Ihre Anwendung verwenden möchten, wählen Sie Empty Compose Activity aus.
   2. Stellen Sie die Sprache auf kotlin ein.
   3. Legen Sie den Mindestwert für das SDK auf API 19: Android 4.4 (KitKat) fest.

4. Achten Sie darauf, dass sich das Maven-Repository google() von Google in der Liste der Repositories in der Datei build.gradle auf Projektebene befindet, wie im folgenden Snippet gezeigt:

   allprojects {
       repositories {
           google()
       }
   }
   

   Weitere Informationen finden Sie unter Maven-Repository von Google.

5. Um die reCAPTCHA Enterprise 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.5.0-beta02'
   

   Weitere Informationen zum Hinzufügen von Abhängigkeiten in Android-Apps finden Sie unter Build-Abhängigkeiten hinzufügen.

6. Fügen Sie im Manifest Ihrer Anwendung zwischen dem ersten <manifest>-Tag und dem ersten <application>-Tag eine Internetberechtigung hinzu (z. B. AndroidManifest.xml). Diese Berechtigung ist erforderlich, da die reCAPTCHA Enterprise API Netzwerkvorgänge umfasst.

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

7. 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 findest du unter Zu AndroidX migrieren.

Flutter

Eine ausführliche Anleitung zur Verwendung von reCAPTCHA Enterprise mit Flutter finden Sie in der Dokumentation zu Flutter.

ReactNative

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

reCAPTCHA Enterprise in Ihre Android-App einbinden

1. Instanziieren Sie einen Client mithilfe des reCAPTCHA-Schlüssels (KEY_ID), den Sie für Ihre Android-App erstellt haben.

   Hinweis: Sie dürfen den reCAPTCHA Enterprise-Client während der Lebensdauer Ihrer Anwendung nur einmal verwenden.

   Kotlin

   class MainActivity : AppCompatActivity() {
   
       private lateinit var recaptchaClient: RecaptchaClient
   
       override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
         setContentView(R.layout.activity_main)
         initializeRecaptchaClient()
         // ... rest of onCreate code
       }
   
       private fun initializeRecaptchaClient() {
         lifecycleScope.launch {
           Recaptcha.getClient(application, "KEY_ID")
             .onSuccess { client ->
               recaptchaClient = client
             }
             .onFailure { exception ->
               // Handle communication errors ...
               // See "Handle communication errors" section
             }
         }
       }
   
       // ... rest of activity code.
   }
   

   Java

   public final class MainActivity extends Activity {
     @Nullable private RecaptchaTasksClient recaptchaTasksClient = null;
   
     @Override
     protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       setContentView(R.layout.activity_main);
       initializeRecaptchaClient();
       // ... rest of onCreate code
     }
   
     private void initializeRecaptchaClient() {
       Recaptcha
         .getTasksClient(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 communication errors ...
                 // See "Handle communication errors" section
               }
             });
     }
   
     // ... rest of activity code.
   }
   

   Hinweis: Wenn die API eine Instanz von ApiException an onFailure() übergibt, müssen Sie jeden möglichen Statuscode verarbeiten, den Sie mit getStatusCode() abrufen können. Weitere Informationen finden Sie unter Umgang mit Kommunikationsfehlern.

2. Rufen Sie für jede Aktion Ihrer Anwendung, die mit reCAPTCHA Enterprise geschützt ist, die Methode execute auf und übergeben Sie dabei RecaptchaAction. reCAPTCHA Enterprise bietet eine integrierte Reihe von Aktionen. Bei Bedarf können Sie auch benutzerdefinierte Aktionen erstellen.

   Das folgende Code-Snippet zeigt, wie Sie mit execute eine LOGIN-Aktion schützen.

   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 communication errors ...
           // See "Handle communication errors" section
         }
     }
   }
   

   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 communication errors ...
               // See "Handle communication errors" section
             }
           });
   }
   

Das folgende Beispielcode-Snippet zeigt eine vollständige Integration der Methoden getClient() und execute() in einer einzelnen Activity-App:

Kotlin

class MainActivity : AppCompatActivity() {

  private lateinit var recaptchaClient: RecaptchaClient

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)
    initializeRecaptchaClient()
    findViewById<View>(R.id.btn_login).setOnClickListener { executeLoginAction() }
    findViewById<View>(R.id.btn_redeem).setOnClickListener { executeRedeemAction() }
  }

  private fun initializeRecaptchaClient() {
    lifecycleScope.launch {
      Recaptcha.getClient(application, "KEY_ID")
        .onSuccess { client ->
          recaptchaClient = client
        }
        .onFailure { exception ->
          // Handle communication errors ...
          // See "Handle communication errors" section
        }
    }
  }

  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 communication errors ...
          // See "Handle communication errors" section
        }
    }
  }

  private fun executeRedeemAction(){
    lifecycleScope.launch {
      recaptchaClient
        .execute(RecaptchaAction.custom("redeem"))
        .onSuccess { token ->
          // Handle success ...
          // See "What's next" section for instructions
          // about handling tokens.
        }
        .onFailure { exception ->
          // Handle communication errors ...
          // See "Handle communication errors" section
        }
    }
  }
}

Java

public final class MainActivity extends Activity {
  @Nullable private RecaptchaTasksClient recaptchaTasksClient = null;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    initializeRecaptchaClient();
    findViewById(R.id.btn_login).setOnClickListener(this::executeLoginAction);
    findViewById(R.id.btn_redeem).setOnClickListener(this::executeRedeemAction);
  }

  private void initializeRecaptchaClient() {
    Recaptcha
      .getTasksClient(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 communication errors ...
              // See "Handle communication errors" section
            }
          });
  }

  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 communication errors ...
              // See "Handle communication errors" section
            }
          });
  }

  private void executeRedeemAction(View v) {
    assert recaptchaTasksClient != null;
    recaptchaTasksClient
      .executeTask(RecaptchaAction.custom("redeem"))
      .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 communication errors ...
              // See "Handle communication errors" section
            }
          });
  }
}

Achtung: getClient() und execute() können mehrere Sekunden auf einem Gerät dauern. Deshalb empfehlen wir Folgendes:

• Initialisieren Sie den Client, wenn die App gestartet wird. Beispiel: Im onCreate()-Aufruf einer benutzerdefinierten Application-Klasse.
• Achte darauf, dass execute()-Aufrufe kein UI-Ereignis blockieren. Die Integration von execute() in deine App sollte kein UI-Ereignis wie das Drücken einer Schaltfläche blockieren. Beispielsweise können Sie execute() beim Erstellen einer Ansicht asynchron aufrufen.

Hinweis :Für den Google Play Store musst du das Google Play-Formular zur Datensicherheit ausfüllen, bevor du deine App in den Play Store hochlädst. In den Pflichten zur Offenlegung von Daten bei Google Play finden Sie alle Informationen, die Sie zum Ausfüllen des Formulars zur Datensicherheit über das reCAPTCHA Enterprise Android SDK benötigen.

Zeitlimit für API-Aufrufe festlegen

Mit dem Attribut timeout der einzelnen APIs können Sie einen Zeitüberschreitungswert für die APIs getClient und execute angeben.

Ein Standardzeitlimit von 10 Sekunden wird für getClient und von 10 Sekunden für execute APIs verwendet.

Kotlin

• Zeitlimit beim Aufrufen von getClient festlegen.

      lifecycleScope.launch {
        Recaptcha.getClient(application, "KEY_ID", timeout = 20000L)
          .onSuccess { client ->
            recaptchaClient = client
          }
          .onFailure { exception ->
            // Handle communication errors ...
            // See "Handle communication errors" section
          }
      }
  

  Mit diesem Code-Snippet wird das Zeitlimit von getClient auf 20 Sekunden festgelegt.

• Zeitlimit beim Aufrufen von execute festlegen.

      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 communication errors ...
            // See "Handle communication errors" section
          }
      }
  

  Mit diesem Code-Snippet wird das Zeitlimit von execute auf 10 Sekunden festgelegt.

Java

• Zeitlimit beim Aufrufen von getClient festlegen.

    Recaptcha
      .getTasksClient(getApplication(), "KEY_ID", 20000L)
      .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 communication errors ...
              // See "Handle communication errors" section
            }
          });
  

  Mit diesem Code-Snippet wird das Zeitlimit von getClient auf 20 Sekunden festgelegt.

• Zeitlimit beim Aufrufen von execute festlegen.

    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 communication errors ...
              // See "Handle communication errors" section
            }
          });
  

  Mit diesem Code-Snippet wird das Zeitlimit von execute auf 10 Sekunden festgelegt.

Kommunikationsfehler beheben

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 zur Risikominimierung aufgrund häufiger API-Fehler finden Sie unter RecaptchaErrorCode.

API-Referenz

Eine vollständige Referenz der reCAPTCHA API for Android findest du unter com.google.android.recaptcha.

Nächste Schritte

• Erstellen Sie eine Bewertung, um das reCAPTCHA-Antworttoken zu bewerten.

  Hinweis: reCAPTCHA-Antworttokens werden von Ihrem Backend-Server aus bewertet und annotiert, nicht vom Mobilgerät aus.