Android SDK

Android 5.0+ (API 21+) に対応した単一 .aar パッケージ。Compose・従来の View ベース、いずれでも組み込み可能で、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:

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

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

xml

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

Build and install the demo with:

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)`	シングルトンの入口。アプリ context にひも付いた共有クライアントを返します。
`CaptchalaConfig.Builder()`	`appKey` / `action` / `lang` / `theme` / `enableVoice` / `enableOfflineMode` / `serverToken` を設定する流れるような Builder。
`init(config)`	組み立て済みの `CaptchalaConfig` でクライアントを初期化します。何度呼び出しても安全（再呼び出し時に再構築）。
`setListener(listener)`	`CaptchalaListener` を登録し、`onReady` / `onSuccess` / `onFail` / `onError` / `onClose` を受け取ります。
`verify(activity)`	指定した Activity 上に CAPTCHA を表示します。結果はリスナー経由で通知されます。
`CaptchalaResult`	`passToken` / `challengeId` / `ttl` / `isOffline` / `isClientOnly` を保持。`passToken` をバックエンドへ送ります。
`CaptchalaClient.destroy()`	シングルトンを破棄（WebView やネイティブハンドルを解放）。再初期化が多い場合は `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>", "client_ip": "<end-user IP>" }

完全な検証エンドポイントと X-App-Key / X-App-Secret のフローは API リファレンスを参照してください。

トラブルシューティング

起動時に UnsatisfiedLinkError
abiFilters が armeabi-v7a / arm64-v8a / x86 / x86_64 を網羅しているか確認してください。デモの 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" のままにしてください（デモがそうしています）。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

Android SDK ​

GitHub のデモ ​

インストール ​

クイックスタート ​

主な API ​

サーバー側検証 ​

トラブルシューティング ​

動作環境 ​