reCAPTCHA Enterprise in Android-Apps einbinden

Auf dieser Seite wird erläutert, wie Sie reCAPTCHA Enterprise in Ihre Android-App einbinden. Aufgrund von Unterschieden bei Mobilgeräten in Bezug auf Bildschirmgröße, Leistung und Benutzeroberflächen der Apps ist das visuelle Kästchen für die reCAPTCHA-Challenge (Ich bin kein Roboter) für mobile Apps nicht verfügbar. Sie können stattdessen eine eigene gestaffelte Erzwingungsstrategie implementieren, z. B. einen MFA-Ablauf, um einen alternativen Einlösepfad für verdächtigen Traffic bereitzustellen.

Wichtig: Das SDK verwendet Reflexion 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 bei der Anwendung zu vermeiden.

Hinweise

1. Wählen Sie die beste Methode zum Einrichten von reCAPTCHA Enterprise in Ihrer Umgebung aus und schließen Sie die Einrichtung ab.

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

Umgebung vorbereiten

Warnung :Migrieren Sie nicht zu Android SDK 18.2.0, da Ihre App aufgrund einiger interner Fehler möglicherweise nicht wie vorgesehen funktioniert. Migrieren Sie direkt zum Android SDK 18.2.1 oder höher, um diese Probleme zu vermeiden. Weitere Informationen finden Sie 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 eine App mit dem Mindestwert für das Android SDK auf API 19: Android 4.4 (KitKat) festgelegt ist. Sie können entweder das Mindest-SDK Ihrer App auf API 19 festlegen oder eine neue mobile App erstellen.

3. Wenn Sie eine neue mobile App erstellen, erstellen Sie eine Testanwendung. Starten Sie dazu ein neues Android Studio-Projekt:

   1. Wählen Sie Leere Aktivität aus. Wenn Sie in Ihrer Anwendung Jetpack Compose verwenden möchten, wählen Sie Leere Compose-Aktivität aus.
   2. Legen Sie die Sprache auf kotlin fest.
   3. Legen Sie für den SDK-Mindestwert 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 im 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.3.0'
   

   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 eine Internetberechtigung zwischen dem ersten <manifest>-Tag und dem ersten <application>-Tag 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 finden Sie unter Zu Android X migrieren.

Flutter

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

Reaktiv

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 mit dem reCAPTCHA-Schlüssel (KEY_ID), den Sie für Ihre Android-App erstellt haben.

   Hinweis: Sie müssen 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, der mit getStatusCode() abgerufen werden kann. Weitere Informationen finden Sie unter Kommunikationsfehler beheben.

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

   Im folgenden Code-Snippet sehen Sie, wie execute zum Schutz einer LOGIN-Aktion verwendet 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 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 eine einzelne Aktivitäts-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: Die Ausführung von getClient() und execute() auf einem Gerät kann einige Sekunden dauern. Daher empfehlen wir Ihnen Folgendes:

• Initialisieren Sie den Client beim Start der App. Beispiel: Im Aufruf onCreate() einer benutzerdefinierten Klasse Application.
• Achten Sie darauf, dass execute()-Aufrufe kein UI-Ereignis blockieren. Durch die Einbindung von execute() in Ihre App sollte kein UI-Ereignis blockiert werden, z. B. das Drücken einer Schaltfläche. Sie können beispielsweise execute() beim Erstellen einer Ansicht asynchron aufrufen.

Hinweis :Für den Google Play Store müssen Sie das Formular zur Datensicherheit von Google Play ausfüllen, bevor Sie Ihre App in den Play Store hochladen. Welche Informationen das reCAPTCHA Enterprise Android SDK zum Ausfüllen des Formulars zur Datensicherheit benötigt, finden Sie in den Anforderungen zur Offenlegung von Daten bei Google Play.

Zeitlimit für API-Aufrufe festlegen

Mit dem Attribut timeout einer API können Sie ein Zeitlimit für die APIs getClient und execute festlegen.

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

Kotlin

• Legen Sie beim Aufrufen von getClient ein Zeitlimit fest.

      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.

• Legen Sie beim Aufrufen von execute ein Zeitlimit 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 communication errors ...
            // See "Handle communication errors" section
          }
      }
  

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

Java

• Legen Sie beim Aufrufen von getClient ein Zeitlimit fest.

    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.

• Legen Sie beim Aufrufen von execute ein Zeitlimit 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 communication errors ...
              // See "Handle communication errors" section
            }
          });
  

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

Mit Kommunikationsfehlern umgehen

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 häufigen API-Fehlern finden Sie unter RecaptchaErrorCode.

API-Referenz

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

Nächste Schritte

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

• Feedback geben, um Feedback zur Genauigkeit der erstellten Bewertung zu geben.

  Hinweis: reCAPTCHA-Antworttokens werden von deinem Back-End-Server geprüft und annotiert, nicht vom Mobilgerät.