Android SDK

SDK для Android для Android 5.0+ (API 21+), поставляется как один .aar. Подходит для приложений на Compose и на View; SDK не зависит от UI-фреймворка.

Демо на GitHub

📦

Captcha-La/android-demo — полный рабочий пример со всеми шагами интеграции.

Установка

SDK поставляется в виде одного .aar, который вы скачиваете из панели управления CaptchaLa. Поместите его в папку libs/ вашего модуля app и подключите через 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'
}

Скачать: dash.captcha.la/downloads (последний AAR).

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

Соберите и установите демо с помощью:

./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)	Singleton-точка входа. Возвращает общий клиент, привязанный к контексту приложения.
CaptchalaConfig.Builder()	Fluent builder для appKey, action, lang, theme, enableVoice, enableOfflineMode, serverToken.
init(config)	Инициализирует клиент с собранной CaptchalaConfig. Вызов недорогой — уничтожает и пересобирает состояние при повторном вызове.
setListener(listener)	Регистрирует CaptchalaListener для callback-ов onReady, onSuccess, onFail, onError, onClose.
verify(activity)	Открывает CAPTCHA поверх указанной Activity. Результат доставляется через listener.
CaptchalaResult	Содержит passToken, challengeId, ttl, isOffline, isClientOnly. Передайте passToken на ваш backend.
CaptchalaClient.destroy()	Уничтожает singleton (освобождает WebView, нативные ресурсы). Вызывайте из Activity.onDestroy, если часто пере-инициализируете.

Серверная проверка

Перешлите result.passToken (или result.token) на ваш backend и проверьте его через API CaptchaLa. Никогда не размещайте 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>" }

См. Справочник API для полного endpoint проверки и потока X-App-Key / X-App-Secret.

Устранение неполадок

• UnsatisfiedLinkError при запуске
  Убедитесь, что ваш abiFilters покрывает armeabi-v7a, arm64-v8a, x86, x86_64, чтобы устройства всех архитектур находили подходящую нативную библиотеку. app/build.gradle в демо показывает точный список фильтров.

• ProGuard / R8 вырезает классы SDK в release
  Добавьте правило keep для пакета SDK, например -keep class la.captcha.sdk.** { *; } и -dontwarn la.captcha.sdk.** в proguard-rules.pro.

• Слишком низкая minSdkVersion
  SDK требует minSdkVersion 21 (Android 5.0). Более низкие значения не пройдут компиляцию.

• Заблокирован cleartext HTTP трафик
  Ваш манифест должен содержать android:usesCleartextTraffic="false" (как в демо). Endpoint CaptchaLa работает только через HTTPS.

Требования

• Android 5.0+ (minSdkVersion 21)
• AndroidX (compileSdk 33+)
• Kotlin 1.8+ или эквивалентная Java-инструментальная цепочка (Java 17 source / target)
• ABI: armeabi-v7a, arm64-v8a, x86, x86_64