reCAPTCHA Enterprise in Android-Apps einbinden

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Auf dieser Seite wird erläutert, wie Sie reCAPTCHA Enterprise in Ihre Android-App einbinden. Aufgrund von Unterschieden bei der Darstellung von Bildschirmgröße, -leistung und -UI bei Mobilgeräten ist das reCAPTCHA-Challenge-Symbol (I'm not a robot) für mobile Apps nicht verfügbar. Sie können stattdessen eine eigene abgestufte Erzwingungsstrategie implementieren, z. B. einen MFA-Vorgang, um einen alternativen Einlösungspfad für verdächtigen Traffic bereitzustellen.

Hinweis

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

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

Umgebung vorbereiten

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

  2. Achten Sie darauf, dass eine App den Android SDK-Mindestwert auf API 19: Android 4.4 (KitKat) festgelegt hat. Sie können entweder das minimale 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, indem Sie ein neues Android Studio-Projekt starten:

    1. Wählen Sie Leere Aktivität aus. Wenn Sie Jetpack Compose in Ihrer Anwendung verwenden möchten, wählen Sie Empty Compose Activity aus.
    2. Legen Sie als Sprache kotlin fest.
    3. Legen Sie als 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 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.0.1'
    

    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 AndroidX migrieren.

reCAPTCHA Enterprise in Android-App einbinden

  1. Instanziieren Sie einen Client mit dem SITE_KEY, den Sie für Ihre Android-App erstellt haben.

    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, "YOUR_SITE_KEY")
              .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(), "YOUR_SITE_KEY")
          .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.
    }
    
  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 integrierte Reihe von Aktionen. Bei Bedarf können Sie auch benutzerdefinierte Aktionen erstellen.

    Das folgende Code-Snippet zeigt, 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 einer einzelnen Activity-Anwendung:

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, "YOUR_SITE_KEY")
        .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(), "YOUR_SITE_KEY")
      .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
            }
          });
  }
}

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 zu Maßnahmen zur Behebung häufig auftretender API-Fehler 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