Integrationsleitfaden

Produkteinführung

Element	Beschreibung
Kernfunktionen	Next-Generation CAPTCHA, das Geschäftsverluste und Sicherheitsrisiken durch automatisierte Angriffe von Skripten intelligent adressiert.
SDK-Datenschutzrichtlinie	Richtlinie
SDK-Compliance-Leitfaden	Leitfaden
SDK-Download	Herunterladen

Systemvoraussetzungen

Element	Ressource
Entwicklungsziel	`Android 5.0+` (minSdk 21)
Entwicklungsumgebung	`Android Studio 2020.3.1 Arctic Fox+`
Build-Tool	`Gradle` (Android Gradle Plugin 7+)
Systemabhängigkeiten	Keine
SDK-Abhängigkeiten von Drittanbietern	Keine
Paketgröße	Verifiziertes SDK: 60K

Integration des SDK

SDK importieren

Ziehen Sie die .aar-Datei (z. B. engagelab_captcha_android_vx.y.z.aar) aus dem ZIP-Paket in den libs-Ordner Ihres Projekts. Nachdem Sie die .aar-Datei verschoben haben, stellen Sie sicher, dass sie zur Bibliothek hinzugefügt wurde. Ergänzen Sie in der build.gradle-Datei Ihres Projekts folgende Konfiguration:

repositories { flatDir { dirs 'libs' } }

              
              repositories {
    flatDir {
        dirs 'libs'
    }
}

Diesen Codeblock im schwebenden Fenster anzeigen

Fügen Sie das aar-Paket außerdem manuell als Abhängigkeit hinzu (das AAR enthält keine Drittanbieter-Abhängigkeiten automatisch, diese müssen also separat ergänzt werden):

implementation(name: 'engagelab_captcha_android_vx.y.z', ext: 'aar')

              
              implementation(name: 'engagelab_captcha_android_vx.y.z', ext: 'aar')

Diesen Codeblock im schwebenden Fenster anzeigen

Konfiguration für Nicht-Kotlin-Projekte

In der build.gradle-Datei im Root-Verzeichnis:

ext.kotlin_version = "1.6.22" dependencies { classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version" }

              
              ext.kotlin_version = "1.6.22"

dependencies {
    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
}

Diesen Codeblock im schwebenden Fenster anzeigen

In der Modul-build.gradle-Datei:

apply plugin: 'kotlin-android' dependencies { implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version" }

              
              apply plugin: 'kotlin-android'
dependencies {
    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
}

Diesen Codeblock im schwebenden Fenster anzeigen

Bei Versionskonflikten mit Kotlin die Kotlin-Abhängigkeit ausschließen: exclude(group: 'org.jetbrains.kotlin')

Berechtigungen hinzufügen

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

              
              <!-- Erforderlich – Standardanwendung -->
<uses-permission android:name="android.permission.INTERNET" />
<!-- Muss für Kompatibilität mit API-Level unter 23 (nicht eingeschlossen) deklariert werden (d. h. Apps auf Android 4.x und 5.x benötigen diese Angabe) – Standardmäßig nicht gesetzt -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Diesen Codeblock im schwebenden Fenster anzeigen

Proguard-Regeln

Das SDK-aar-Paket ist bereits obfuskiert. Eine doppelte Obfuskation kann zu unerwarteten Fehlern führen. Standardmäßig enthält das AAR-Paket die aktuelle Obfuskationskonfiguration des SDK. Sowohl Remote- als auch lokale AAR-Abhängigkeiten stellen sicher, dass das SDK nicht erneut obfuskiert wird.
Wenn Sie das AAR-Paket extrahieren und die JAR- sowie Ressourcendateien separat integrieren, kopieren Sie unbedingt den Inhalt der Datei proguard.txt aus dem extrahierten Verzeichnis in Ihre Obfuskationskonfiguration, um eine doppelte Obfuskation des SDK zu vermeiden.

Wenn Sie andRes zur Ressourcenobfuskation verwenden, schließen Sie die im SDK enthaltenen Ressourcen von der Obfuskation aus, um Fehler durch fehlende Ressourcen zu vermeiden. Die Ausschlusskonfiguration lautet wie folgt:

"R.string.gt4_*", "R.style.gt4_*",

              
              "R.string.gt4_*",
"R.style.gt4_*",

Diesen Codeblock im schwebenden Fenster anzeigen

Schnittstellenkonfiguration

Ablauf der Produktintegration

Initialisierung konfigurieren
Verifizierung starten
Verifizierungs-Callback empfangen
Ressourcen freigeben

Weitere Informationen zum Ablauf finden Sie im Ablauf der Produktintegration. Sie müssen zunächst das entsprechende Server-Schnittstelle-Backend einrichten und die captchaId sowie den Key aus der EngageLab Management Console konfigurieren.

Initialisierung

Die Initialisierung des SDK kann in der Methode onCreate oder onCreateView erfolgen.

Methodenbeschreibung

public static GTCaptcha4Client getClient(Context context); public GTCaptcha4Client init(String captchaId); public GTCaptcha4Client init(String captchaId, GTCaptcha4Config config)

              
              public static GTCaptcha4Client getClient(Context context);
public GTCaptcha4Client init(String captchaId);
public GTCaptcha4Client init(String captchaId, GTCaptcha4Config config)

Diesen Codeblock im schwebenden Fenster anzeigen

Parameterbeschreibung

Parameter	Typ	Beschreibung
`context`	`Context`	Context-Objekt, muss eine Activity-Instanz sein
`appId`	`String`	APP_ID, erforderlicher Parameter
`config`	`GTCaptcha4Config`	Konfigurationsobjekt, optional

Die Methode init() startet das Preloading. Erfolgt die Initialisierung in onCreate oder onCreateView, wird der Verifizierungsprozess vorab geladen und ermöglicht eine schnellere Verifizierung. Wird init() erst beim Verifizierungsaufruf ausgeführt, ist das Laden langsamer. Es wird empfohlen, die Initialisierung in onCreate oder onCreateView vorzunehmen.

Verifizierung starten

Startet den Verifizierungsprozess.

Methodenbeschreibung

public void verifyWithCaptcha();

              
              public void verifyWithCaptcha();

Diesen Codeblock im schwebenden Fenster anzeigen

Verifizierung abbrechen

Bricht den Verifizierungsprozess ab und schließt das Verifizierungsfenster.

Methodenbeschreibung

public void cancel();

              
              public void cancel();

Diesen Codeblock im schwebenden Fenster anzeigen

Protokollüberwachung aktivieren/deaktivieren

Aktiviert oder deaktiviert die Protokollüberwachung.

Methodenbeschreibung

public void setLogEnable(boolean enable);

              
              public void setLogEnable(boolean enable);

Diesen Codeblock im schwebenden Fenster anzeigen

Verifizierungs-Callback empfangen

public GTCaptcha4Client addOnSuccessListener(OnSuccessListener listener); public GTCaptcha4Client addOnFailureListener(OnFailureListener listener); public GTCaptcha4Client addOnWebViewShowListener(OnWebViewShowListener listener);

              
              public GTCaptcha4Client addOnSuccessListener(OnSuccessListener listener);
public GTCaptcha4Client addOnFailureListener(OnFailureListener listener);
public GTCaptcha4Client addOnWebViewShowListener(OnWebViewShowListener listener);

Diesen Codeblock im schwebenden Fenster anzeigen

Codebeispiel

gtCaptcha4Client.addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener() { @Override public void onSuccess(boolean status, String response) { if(status){ // TODO Zweite Verifizierung aktivieren }else { // TODO Antwort der Benutzer:innen fehlgeschlagen } } }).addOnFailureListener(new GTCaptcha4Client.OnFailureListener() { @Override public void onFailure(String error) { } }).addOnWebViewShowListener(new GTCaptcha4Client.OnWebViewShowListener() { @Override public void onWebViewShow() { } })

              
              gtCaptcha4Client.addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener() {
    @Override
    public void onSuccess(boolean status, String response) {
        if(status){
            // TODO Zweite Verifizierung aktivieren
        }else {
            // TODO Antwort der Benutzer:innen fehlgeschlagen
        }
    }
}).addOnFailureListener(new GTCaptcha4Client.OnFailureListener() {
    @Override
    public void onFailure(String error) {
    }
}).addOnWebViewShowListener(new GTCaptcha4Client.OnWebViewShowListener() {
      @Override
      public void onWebViewShow() {
      }
  })

Diesen Codeblock im schwebenden Fenster anzeigen

Ressourcen freigeben

Ressourcen im onDestroy-Lebenszyklus freigeben:

public void onDestroy(){ super.onDestroy(); if(gtCaptcha4Client != null){ gtCaptcha4Client.destroy(); } }

              
              public void onDestroy(){
    super.onDestroy();
    if(gtCaptcha4Client != null){
        gtCaptcha4Client.destroy();
    }
}

Diesen Codeblock im schwebenden Fenster anzeigen

Bildschirmorientierung ändern

@Override public void onConfigurationChanged(Configuration newConfig) { super.onConfigurationChanged(newConfig); if(gtCaptcha4Client != null){ gtCaptcha4Client.configurationChanged(newConfig); } }

              
              @Override
public void onConfigurationChanged(Configuration newConfig) {
    super.onConfigurationChanged(newConfig);
    if(gtCaptcha4Client != null){
        gtCaptcha4Client.configurationChanged(newConfig);
    }
}

Diesen Codeblock im schwebenden Fenster anzeigen

Preloading – Codebeispiel

@Override public void onViewCreated(View view, Bundle savedInstanceState){ super.onViewCreated(view, savedInstanceState); String[] apiServers = {"captcha-api.engagelab.com"}; String[] staticServers = {"captcha-stat.engagelab.com/www/js"}; GTCaptcha4Config config = new GTCaptcha4Config.Builder() // Dienstadresse festlegen .setResourcePath("https://captcha-stat.engagelab.com/www/gt4-index.html") .setApiServers(apiServers) .setStaticServers(staticServers) .setDebug(true) // TODO In Produktion deaktivieren .setLanguage("zh") .setTimeOut(10000) .setCanceledOnTouchOutside(true) .build(); gtCaptcha4Client = GTCaptcha4Client.getClient(activity) .init("your captcha_id", config); } private void click(){ gtCaptcha4Client.addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener { @Override public void onSuccess(boolean status, String response) { if(status){ // TODO Zweite Verifizierung aktivieren }else { // TODO Antwort der Benutzer:innen fehlgeschlagen } } }) .addOnFailureListener(new GTCaptcha4Client.OnFailureListener { @Override public void onFailure(String error) { } }) .verifyWithCaptcha(); }

              
              @Override
public void onViewCreated(View view, Bundle savedInstanceState){
    super.onViewCreated(view, savedInstanceState);
    String[] apiServers = {"captcha-api.engagelab.com"};
    String[] staticServers = {"captcha-stat.engagelab.com/www/js"};
    GTCaptcha4Config config = new GTCaptcha4Config.Builder()
            // Dienstadresse festlegen
            .setResourcePath("https://captcha-stat.engagelab.com/www/gt4-index.html")
            .setApiServers(apiServers)
            .setStaticServers(staticServers)
            .setDebug(true) // TODO In Produktion deaktivieren
            .setLanguage("zh")
            .setTimeOut(10000)
            .setCanceledOnTouchOutside(true)
            .build();
    gtCaptcha4Client = GTCaptcha4Client.getClient(activity)
            .init("your captcha_id", config);
}

private void click(){
    gtCaptcha4Client.addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener {
                @Override
                public void onSuccess(boolean status, String response) {
                    if(status){
                        // TODO Zweite Verifizierung aktivieren
                    }else {
                        // TODO Antwort der Benutzer:innen fehlgeschlagen
                    }
                }
            })
            .addOnFailureListener(new GTCaptcha4Client.OnFailureListener {
                @Override
                public void onFailure(String error) {
                }
            })
            .verifyWithCaptcha();
}

Diesen Codeblock im schwebenden Fenster anzeigen

Normales Laden – Codebeispiel

private void click(){ String[] apiServers = {"captcha-api.engagelab.com"}; String[] staticServers = {"captcha-stat.engagelab.com/www/js"}; GTCaptcha4Config config = new GTCaptcha4Config.Builder() // Dienstadresse festlegen .setResourcePath("https://captcha-stat.engagelab.com/www/gt4-index.html") .setApiServers(apiServers) .setStaticServers(staticServers) .setDebug(true) // TODO In Produktion deaktivieren .setLanguage("zh") .setTimeOut(10000) .setCanceledOnTouchOutside(true) .build(); gtCaptcha4Client = GTCaptcha4Client.getClient(activity) .init("your captcha_id", config) .addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener { @Override public void onSuccess(boolean status, String response) { if(status){ // TODO Zweite Verifizierung aktivieren }else { // TODO Antwort der Benutzer:innen fehlgeschlagen } } }) .addOnFailureListener(new GTCaptcha4Client.OnFailureListener { @Override public void onFailure(String error) { } }) .verifyWithCaptcha(); }

              
              private void click(){
    String[] apiServers = {"captcha-api.engagelab.com"};
    String[] staticServers = {"captcha-stat.engagelab.com/www/js"};
    GTCaptcha4Config config = new GTCaptcha4Config.Builder()
            // Dienstadresse festlegen
            .setResourcePath("https://captcha-stat.engagelab.com/www/gt4-index.html")
            .setApiServers(apiServers)
            .setStaticServers(staticServers)
            .setDebug(true) // TODO In Produktion deaktivieren
            .setLanguage("zh")
            .setTimeOut(10000)
            .setCanceledOnTouchOutside(true)
            .build();
    gtCaptcha4Client = GTCaptcha4Client.getClient(activity)
            .init("your captcha_id", config)
            .addOnSuccessListener(new GTCaptcha4Client.OnSuccessListener {
                @Override
                public void onSuccess(boolean status, String response) {
                    if(status){
                        // TODO Zweite Verifizierung aktivieren
                    }else {
                        // TODO Antwort der Benutzer:innen fehlgeschlagen
                    }
                }
            })
            .addOnFailureListener(new GTCaptcha4Client.OnFailureListener {
                @Override
                public void onFailure(String error) {
                }
            })
            .verifyWithCaptcha();
}

Diesen Codeblock im schwebenden Fenster anzeigen

Für weitere Codebeispiele siehe das offizielle Demo.

Parameterkonfiguration

Konfigurieren Sie Parameter über die Klasse GTCaptcha4Config.Builder:

Definition	Beschreibung
`setResourcePath`	Muss gesetzt werden auf: https://captcha-stat.engagelab.com/www/gt4-index.html
`setApiServers`	Muss gesetzt werden auf: captcha-api.engagelab.com
`setStaticServers`	Muss gesetzt werden auf: captcha-stat.engagelab.com/www/js
`setParams`	Zusätzliche Parameter, die an das Frontend-JS übergeben werden
`setDebug`	Aktiviert Debug-Modus, Standard ist `false`, in Produktion auf `false` setzen
`setLanguage`	Sprache festlegen, Standard ist die App-Sprache
`setCanceledOnTouchOutside`	Schließen bei Antippen außerhalb, Standard ist `true`
`setTimeOut`	Timeout in ms festlegen, Standard ist 10.000
`setBackgroundColor`	Hintergrundfarbe festlegen, Standard ist transparent
`setDialogStyle`	Dialog-Themenstil festlegen, Standard ist `gt4_captcha_dialog_style`
`setDialogShowListener`	Listener-Callback für das Anzeigen des Verifizierungsfensters
`build`	Erstellt das GTCaptcha4Config-Objekt

Parameter können gemäß API-Dokumentation über die setParams-Schnittstelle konfiguriert werden.

Die setParams-Schnittstelle akzeptiert nur Basisdatentypen, Strings und Daten vom Typ JSONArray.

Fehlerbehandlung

Während der Verifizierung können unerwartete Fehler auftreten. Sie können diese behandeln, indem Sie die addOnFailureListener-Schnittstelle implementieren und im folgenden Callback verarbeiten:

Hinweis: Fehler-Callbacks umfassen auch von Benutzer:innen abgebrochene Verifizierungen, diese können separat gefiltert werden.

gtCaptcha4Client.addOnFailureListener(new GTCaptcha4Client.OnFailureListener() { @Override public void onFailure(String error){ // Beispiel für zurückgegebenen Fehlerinhalt // {"code":"-14460","msg":"Verification session canceled","desc":{"description":"User cancelled 'Captcha'"}} // Sie können den Fehler als JSON parsen, die Fehlerbeschreibung ersetzen und den Fehlercode beibehalten Toast.makeText(context, "Fehler bei der Verifizierung: $error", Toast.LENGTH_SHORT).show(); } });

              
              gtCaptcha4Client.addOnFailureListener(new GTCaptcha4Client.OnFailureListener() {
    @Override
    public void onFailure(String error){
        // Beispiel für zurückgegebenen Fehlerinhalt
        // {"code":"-14460","msg":"Verification session canceled","desc":{"description":"User cancelled 'Captcha'"}}
        // Sie können den Fehler als JSON parsen, die Fehlerbeschreibung ersetzen und den Fehlercode beibehalten
        Toast.makeText(context, "Fehler bei der Verifizierung: $error", Toast.LENGTH_SHORT).show();
    }
});

Diesen Codeblock im schwebenden Fenster anzeigen

Es wird dringend empfohlen, den Fehlercode zusammen mit dem Fehlergrund an Benutzer:innen anzuzeigen, um die Online-Fehlerbehebung zu erleichtern.

Eine Liste möglicher Fehlercodes finden Sie hier: Fehlercodeliste

Android CAPTCHA-Integrationsanleitung

Produkteinführung

Systemvoraussetzungen

Integration des SDK

SDK importieren

Konfiguration für Nicht-Kotlin-Projekte

Berechtigungen hinzufügen

Proguard-Regeln

Schnittstellenkonfiguration

Ablauf der Produktintegration

Initialisierung

Verifizierung starten

Verifizierung abbrechen

Protokollüberwachung aktivieren/deaktivieren

Verifizierungs-Callback empfangen

Ressourcen freigeben

Bildschirmorientierung ändern

Preloading – Codebeispiel

Normales Laden – Codebeispiel

Parameterkonfiguration

Fehlerbehandlung