---
title: Android SDK
---

# Android SDK

支援 **Android 5.0+（API 21+）**，以單一 `.aar` 形式發行。Compose 與傳統 View 體系都可接入，SDK 與 UI 框架無關。

## GitHub 上的範例

::: tip 📦
[Captcha-La/android-demo](https://github.com/Captcha-La/android-demo) — 完整可執行範例，包含所有整合步驟。
:::

## 安裝

SDK 以單一 `.aar` 形式發行，可從 [CaptchaLa 控制台](https://dash.captcha.la) 下載。將其放入 app 模組的 `libs/` 資料夾，再於 Gradle 中引用：

```groovy
// 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 手動整合:

```groovy
// 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'
}
```

下載位置：[dash.captcha.la/downloads](https://dash.captcha.la/downloads)（最新版 AAR）。

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

建置並安裝 demo：

```bash
./gradlew installDebug
```

## 快速開始

```kotlin
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 handle）。如果經常重新初始化，可在 `Activity.onDestroy` 中呼叫。 |

## 伺服器端驗證

將 `result.passToken`（或 `result.token`）送到你的後端，再呼叫 CaptchaLa API 驗證。**切勿在用戶端程式碼中暴露 `X-App-Secret`**。

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

完整驗證端點及 `X-App-Key` / `X-App-Secret` 流程請見 [API 參考](../api-reference)。

## 常見問題

- **啟動時 `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+ 或等效的 Java toolchain（Java 17 source / target）
- ABIs: `armeabi-v7a`, `arm64-v8a`, `x86`, `x86_64`