Android-SDK

Android-SDK für Android 5.0+ (API 21+), ausgeliefert als einzelne .aar-Datei. Sowohl Compose- als auch View-basierte Apps werden unterstützt; das SDK ist UI-Framework-unabhängig.

Demo auf GitHub

📦

Captcha-La/android-demo — vollständiges lauffähiges Beispiel mit allen Integrationsschritten.

Installation

Das SDK wird als einzelne .aar-Datei ausgeliefert, die Sie aus dem CaptchaLa-Dashboard herunterladen. Legen Sie sie in den libs/-Ordner Ihres App-Moduls und referenzieren Sie sie aus Gradle:

// settings.gradle (or repositories block)
dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

// app/build.gradle
android {
    defaultConfig {
        minSdk 21
    }
}

dependencies {
    implementation 'la.captcha:captchala:1.0.2'   // Maven Central
}

Oder laden Sie die AAR für eine manuelle Integration herunter:

// app/build.gradle (drop captchala.aar into app/libs/)
android {
    defaultConfig {
        minSdk 21
        ndk {
            abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
        }
    }
}

dependencies {
    implementation files('libs/captchala.aar')
    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3'
    implementation 'androidx.appcompat:appcompat:1.6.1'
    implementation 'com.google.code.gson:gson:2.10.1'
    implementation 'org.bouncycastle:bcprov-jdk18on:1.77'
}

Download: dash.captcha.la/downloads (neueste AAR).

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

Bauen und installieren Sie die Demo mit:

./gradlew installDebug

Schnellstart

import la.captcha.sdk.CaptchalaClient
import la.captcha.sdk.CaptchalaConfig
import la.captcha.sdk.CaptchalaError
import la.captcha.sdk.CaptchalaListener
import la.captcha.sdk.CaptchalaResult

class LoginActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // 1. Fetch a one-shot server_token from YOUR backend
        //    (which calls the CaptchaLa server API with X-App-Key + X-App-Secret).
        val serverToken = runBlocking { fetchServerTokenFromYourBackend() }

        // 2. Build config — destroy any prior client so a fresh state is built.
        CaptchalaClient.destroy()
        val client = CaptchalaClient.getClient(applicationContext).init(
            CaptchalaConfig.Builder()
                .appKey("YOUR_APP_KEY")
                .action("login")            // login, register, pay, …
                .lang("en")                 // en, zh-CN, zh-TW, ja, ko, ms, vi, id
                .theme("light")             // "light" | "dark"
                .enableVoice(true)
                .enableOfflineMode(true)
                .serverToken(serverToken)
                .onServerTokenExpired { fetchServerTokenFromYourBackend() }
                .build()
        )

        // 3. Listen for terminal events.
        client.setListener(object : CaptchalaListener {
            override fun onReady() { /* challenge UI ready */ }
            override fun onSuccess(result: CaptchalaResult) {
                // Send result.passToken to your backend for validation.
                sendToBackend(result.passToken)
            }
            override fun onFail(error: CaptchalaError)  { /* recoverable */ }
            override fun onError(error: CaptchalaError) { /* terminal */ }
            override fun onClose() { /* user dismissed */ }
        })

        // 4. Open the CAPTCHA from a button tap.
        findViewById<Button>(R.id.btnVerify).setOnClickListener {
            client.verify(this)
        }
    }
}

API-Übersicht

Symbol	Zweck
CaptchalaClient.getClient(ctx)	Singleton-Einstiegspunkt. Liefert den gemeinsamen, an den App-Kontext gebundenen Client zurück.
CaptchalaConfig.Builder()	Fluent Builder für appKey, action, lang, theme, enableVoice, enableOfflineMode, serverToken.
init(config)	Initialisiert den Client mit einer gebauten CaptchalaConfig. Günstig aufrufbar — wird er erneut aufgerufen, wird der Status zerstört und neu aufgebaut.
setListener(listener)	Registriert einen CaptchalaListener für die Callbacks onReady, onSuccess, onFail, onError, onClose.
verify(activity)	Öffnet das CAPTCHA über der angegebenen Activity. Das Ergebnis wird über den Listener zugestellt.
CaptchalaResult	Enthält passToken, challengeId, ttl, isOffline, isClientOnly. Senden Sie passToken an Ihr Backend.
CaptchalaClient.destroy()	Baut das Singleton ab (WebView, native Handles freigeben). Aus Activity.onDestroy aufrufen, wenn Sie häufig neu initialisieren.

Serverseitige Validierung

Leiten Sie result.passToken (oder result.token) an Ihr Backend weiter und validieren Sie ihn gegen die CaptchaLa-API. Geben Sie X-App-Secret niemals im Client-Code preis.

POST https://apiv1.captcha.la/v1/validate
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/json

{ "pass_token": "<result.passToken>", "client_ip": "<end-user IP>" }

Siehe die API-Referenz für den vollständigen Validierungs-Endpoint und den X-App-Key / X-App-Secret-Flow.

Fehlerbehebung

• UnsatisfiedLinkError beim Start
  Stellen Sie sicher, dass Ihre abiFilters armeabi-v7a, arm64-v8a, x86, x86_64 abdecken, damit alle Geräteformen eine passende Native Lib finden. Die app/build.gradle der Demo zeigt die exakte Filterliste.

• ProGuard / R8 entfernt SDK-Klassen im Release
  Fügen Sie eine Keep-Regel für das SDK-Paket hinzu, z. B. -keep class la.captcha.sdk.** { *; } und -dontwarn la.captcha.sdk.** in Ihrer proguard-rules.pro.

• minSdkVersion zu niedrig
  Das SDK erfordert minSdkVersion 21 (Android 5.0). Niedrigere Targets schlagen zur Compile-Zeit fehl.

• Cleartext-HTTP-Verkehr blockiert
  Ihr Manifest sollte android:usesCleartextTraffic="false" setzen (so macht es die Demo). Der CaptchaLa-Endpoint ist ausschließlich HTTPS.

Voraussetzungen

• Android 5.0+ (minSdkVersion 21)
• AndroidX (compileSdk 33+)
• Kotlin 1.8+ oder gleichwertige Java-Toolchain (Java 17 Source/Target)
• ABIs: armeabi-v7a, arm64-v8a, x86, x86_64