Android SDK

支持 Android 5.0+（API 21+），以单个 .aar 形式分发。Compose、传统 View 体系都可以接入，SDK 与 UI 框架无关。

GitHub 上的示例

📦

Captcha-La/android-demo — 完整可运行示例，包含所有集成步骤。

安装

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
}

或者下载 AAR 手动集成:

// 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

快速开始

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 一览

符号	用途
CaptchalaClient.getClient(ctx)	单例入口，返回与 application context 绑定的共享客户端。
CaptchalaConfig.Builder()	链式 Builder，用于设置 appKey、action、lang、theme、enableVoice、enableOfflineMode、serverToken。
init(config)	用构建好的 CaptchalaConfig 初始化客户端。可重复调用，会销毁并重建状态。
setListener(listener)	注册 CaptchalaListener，处理 onReady / onSuccess / onFail / onError / onClose 回调。
verify(activity)	在指定 Activity 上弹出验证码，结果通过 listener 回调返回。
CaptchalaResult	包含 passToken、challengeId、ttl、isOffline、isClientOnly。把 passToken 发到你的后端。
CaptchalaClient.destroy()	销毁单例（释放 WebView、native 句柄）。如果频繁重新初始化，可在 Activity.onDestroy 中调用。

服务端校验

把 result.passToken（或 result.token）发到你的后端，再调用 CaptchaLa API 校验。绝不要在客户端代码中暴露 X-App-Secret。

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

完整校验接口及 X-App-Key / X-App-Secret 流程见 API 参考。

常见问题

• 启动时 UnsatisfiedLinkError
  确保 abiFilters 覆盖 armeabi-v7a、arm64-v8a、x86、x86_64，让所有机型都能找到匹配的 native 库。demo 的 app/build.gradle 中可看到具体配置。

• ProGuard / R8 在 release 构建中移除了 SDK 类
  在 proguard-rules.pro 中加入对 SDK 包的 keep 规则，如 -keep class la.captcha.sdk.** { *; } 和 -dontwarn la.captcha.sdk.**。

• minSdkVersion 设得过低
  SDK 要求 minSdkVersion 21（Android 5.0），更低版本会在编译期失败。

• Cleartext HTTP 流量被阻止
  manifest 中应保持 android:usesCleartextTraffic="false"（demo 即如此）。CaptchaLa 端点仅支持 HTTPS。

环境要求

• 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