Android SDK

SDK Android untuk Android 5.0+ (API 21+), dibungkus sebagai satu .aar. Aplikasi Compose dan berasaskan View kedua-duanya disokong; SDK ini tidak terikat pada mana-mana rangka kerja UI.

Demo di GitHub

📦

Captcha-La/android-demo — contoh lengkap yang boleh dijalankan dengan semua langkah integrasi.

Pemasangan

The SDK ships as a single .aar you download from the CaptchaLa dashboard. Drop it into your app module's libs/ folder and reference it from 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
}

Atau muat turun AAR untuk integrasi manual:

// 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 (latest AAR).

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

Build and install the demo with:

./gradlew installDebug

Mula pantas

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 utama

Simbol	Tujuan
CaptchalaClient.getClient(ctx)	Titik masuk singleton. Mengembalikan klien dikongsi yang terikat pada konteks aplikasi.
CaptchalaConfig.Builder()	Builder lancar untuk appKey, action, lang, theme, enableVoice, enableOfflineMode, serverToken.
init(config)	Memulakan klien dengan CaptchalaConfig yang telah dibina. Boleh dipanggil semula — akan dibina semula keadaan.
setListener(listener)	Mendaftar CaptchalaListener untuk panggilan balik onReady, onSuccess, onFail, onError, onClose.
verify(activity)	Membuka CAPTCHA di atas Activity yang diberikan. Keputusan dikembalikan melalui listener.
CaptchalaResult	Mengandungi passToken, challengeId, ttl, isOffline, isClientOnly. Hantar passToken ke backend anda.
CaptchalaClient.destroy()	Memusnahkan singleton (membebaskan WebView, pemegang asli). Panggil dari Activity.onDestroy jika sering memulakan semula.

Pengesahan di pelayan

Hantar result.passToken (atau result.token) ke backend anda dan sahkan menerusi API CaptchaLa. Jangan dedahkan X-App-Secret dalam kod klien.

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>" }

Lihat Rujukan API untuk endpoint pengesahan penuh dan aliran X-App-Key / X-App-Secret.

Penyelesaian masalah

• UnsatisfiedLinkError semasa permulaan
  Pastikan abiFilters merangkumi armeabi-v7a, arm64-v8a, x86, x86_64 supaya semua bentuk peranti menemukan lib asli yang sepadan. Lihat app/build.gradle dalam demo.

• ProGuard / R8 menghapus kelas SDK dalam binaan release
  Tambahkan peraturan kekal untuk pakej SDK, mis. -keep class la.captcha.sdk.** { *; } dan -dontwarn la.captcha.sdk.** dalam proguard-rules.pro.

• minSdkVersion terlalu rendah
  SDK memerlukan minSdkVersion 21 (Android 5.0). Sasaran lebih rendah akan gagal pada masa kompil.

• Trafik HTTP cleartext disekat
  Manifes anda perlu mengekalkan android:usesCleartextTraffic="false" (demo berbuat demikian). Hujung CaptchaLa hanya HTTPS.

Keperluan

• Android 5.0+ (minSdkVersion 21)
• AndroidX (compileSdk 33+)
• Kotlin 1.8+ or equivalent Java toolchain (Java 17 source / target)
• ABIs: armeabi-v7a, arm64-v8a, x86, x86_64