Android-Apps instrumentieren

Auf dieser Seite wird erläutert, wie Sie die reCAPTCHA Enterprise API in Ihrer Android-App anpassen. Weitere Informationen zu reCAPTCHA Enterprise finden Sie in der Übersicht zu reCAPTCHA Enterprise.

Hinweis

  1. Führen Sie die Schritte im Schnellstart aus, um Zugriff auf die API zu erhalten.
  2. Erstellen Sie einen reCAPTCHA-Schlüssel.

Bereiten Sie Ihre Entwicklungsumgebung vor

Laden Sie die neueste Version von Android Studio herunter und installieren Sie sie.

App-Integration

Starten Sie ein neues Android Studio-Projekt mit einer Empty Activity und einer Mindest-API-Stufe 16, um eine Testanwendung zu erstellen.

Maven-Repository-Abhängigkeit von Google hinzufügen

Um eine Abhängigkeit zum reCAPTCHA SDK hinzuzufügen, müssen Sie das Maven-Repository von Google zu Ihrem Projekt hinzufügen. Fügen Sie dazu das folgende Maven-Snippet in den Konfigurationsbereich der Repositories in die Datei build.gradle auf Projektebene ein:

allprojects {
    repositories {
        google()

        // If you're using a version of Gradle lower than 4.1, you must instead use:
        // maven {
        //     url 'https://maven.google.com'
        // }
        // An alternative URL is 'https://dl.google.com/dl/android/maven2/'
    }
}

Weitere Informationen finden Sie im Maven-Repository von Google.

reCAPTCHA-API-Abhängigkeit hinzufügen

Bevor Sie die reCAPTCHA API verwenden können, müssen Sie die reCAPTCHA API zu Ihrem Projekt hinzufügen. Fügen Sie die Build-Regel aus dem folgenden Code-Snippet in den Abschnitt "Abhängigkeiten" Ihres build.gradle auf App-Ebene ein:

apply plugin: 'com.android.application'
...
dependencies {
    implementation 'com.google.android.gms:play-services-recaptcha:16.0.0'
}

Weitere Informationen finden Sie unter Google Play-Dienste einrichten.

Internetberechtigung hinzufügen

Unsere APIs umfassen Netzwerkvorgänge. Damit Sie Netzwerkvorgänge in Ihrer Anwendung durchführen können, muss Ihr Manifest (z. B. AndroidManifest.xml) die folgende Berechtigung zwischen dem ersten <manifest>-Tag und dem ersten <application>-Tag hinzufügen.

<manifest ...?>

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

    <application ...>
    ...
  </application>
</manifest>

gradle.properties zur Verwendung von AndroidX aktualisieren

Fügen Sie die folgenden zwei Zeilen zur Datei "gradle.properties" hinzu, wenn Sie das SDK nicht unter Android 9.0 kompilieren möchten. Weitere Informationen finden Sie unter Zu AndroidX migrieren:

android.useAndroidX=true
android.enableJetifier=true

reCAPTCHA APIs verwenden

reCAPTCHA APIs umfassen drei Methoden: init(), execute() und close(). Zum Aufrufen von reCAPTCHA rufen Sie die drei Methoden in der angegebenen Reihenfolge auf. Normalerweise entspricht die Methode execute() dem Nutzer, der ein UI-Element in Ihrer Aktivität auswählt, z. B. eine Anmeldeschaltfläche.

Der gesamte Ablauf für reCAPTCHA APIs umfasst insbesondere die folgende Abfolge von Aufrufen:

  1. Rufen Sie init() auf, sobald Sie Ihre App oder die Aktivität mit der zu schützenden Aktion starten, um eine RecaptchaHandle zu initialisieren.
    • Recaptcha.getClient(this).init("YOUR_SITE_KEY")
  2. Rufen Sie execute() auf, nachdem die zu schützende Aktion ausgeführt wurde, beispielsweise Klicken auf die Anmeldeschaltfläche. Dann wird ein RecaptchaResults-Token zurückgegeben.
    • Recaptcha.getClient(this).execute(handle, action)
  3. Rufen Sie close() auf, wenn Sie das RecaptchaHandle nicht erneut verwenden werden.
    • Recaptcha.getClient(this).close(handle)
.

Wenn Sie die drei Methoden in Ihrer Anwendung aufrufen, müssen Sie die Methoden onSuccess() und onFailure() überschreiben, um die möglichen Ergebnisse der API-Aufrufe zu verarbeiten. Insbesondere 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 Kommunikationsfehler verarbeiten.

Das folgende Code-Snippet zeigt, wie diese drei Methoden aufgerufen werden:

public final class MainActivity extends Activity {
   private RecaptchaHandle handle;

   @Override
   protected void onCreate(Bundle savedInstanceState) {
     super.onCreate(savedInstanceState);
     setContentView(R.layout.activity_main);

     // Step 1: Call init() once the activity starts.
     Recaptcha.getClient(this)
         .init("YOUR_SITE_KEY")
         .addOnSuccessListener(
             this,
             new OnSuccessListener<RecaptchaHandle>() {
               @Override
               public void onSuccess(RecaptchaHandle handle) {
                 // Handle success ...
                 MainActivity.this.handle = handle;
               }
             })
         .addOnFailureListener(
             this,
             new OnFailureListener() {
               @Override
               public void onFailure(@NonNull Exception e) {
                 if (e instanceof ApiException) {
                   ApiException apiException = (ApiException) e;
                   Status apiErrorStatus = apiException.getStatusCode();
                   // Handle api errors ...
                 } else {
                   // Handle other failures ...
                 }
               }
             });
   }

   public void onClick(View v) {
     // Step 2: call execute() when there is an action to protect.
     Recaptcha.getClient(this)
         .execute(this.handle, new RecaptchaAction(new RecaptchaActionType(RecaptchaActionType.LOGIN)))
         .addOnSuccessListener(
             this,
             new OnSuccessListener<RecaptchaResultData>() {
               @Override
               public void onSuccess(RecaptchaResultData response) {
                 String token = response.getTokenResult();
                 // Handle success ...
                 if (!token.isEmpty()) {
                   Log.d(TAG, "reCAPTCHA response token: " + token);
                   // Validate the response token by following the instruction
                   // in the Create an Assessment topic.
                 }
               }
             })
         .addOnFailureListener(
             this,
             new OnFailureListener() {
               @Override
               public void onFailure(@NonNull Exception e) {
                 if (e instanceof ApiException) {
                   ApiException apiException = (ApiException) e;
                   Status apiErrorStatus = apiException.getStatusCode();
                   // Handle api errors ...
                 } else {
                   // Handle other failures ...
                 }
               }
             });
   }

  @Override
  protected void onDestroy() {
    // Step 3: call close() when there is no more action to verify.
   Recaptcha.getClient(this)
       .close(handle)
       .addOnSuccessListener(
           this,
           new OnSuccessListener<Boolean>() {
             @Override
             public void onSuccess(Boolean gotClosed) {
               // Handle success ...
             }
           })
       .addOnFailureListener(
           this,
           new OnFailureListener() {
             @Override
             public void onFailure(@NonNull Exception e) {
               if (e instanceof ApiException) {
                 ApiException apiException = (ApiException) e;
                 Status apiErrorStatus = apiException.getStatusCode();
                 // Handle api errors ...
               } else {
                 // Handle other failures ...
               }
             }
           });
  }
}

Bewertung erstellen

Befolgen Sie zum Validieren des reCAPTCHA-Antworttokens die Anweisungen zum Erstellen eines Bewertung mit reCAPTCHA Enterprise.

Umgang mit Kommunikationsfehlern

Wenn Ihre Anwendung nicht mit dem reCAPTCHA-Dienst kommunizieren kann, liegt dies möglicherweise daran, dass bei der API ein Fehler auftritt. Sie sollten in Ihrer Anwendung eine Logik hinzufügen, damit ein solcher Fehler ordnungsgemäß verarbeitet werden kann.

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

API-Referenz

Eine vollständige Referenz der APIs finden Sie unter com.google.android.gms.recaptcha.