SDK Android

SDK Android pour Android 5.0+ (API 21+), distribué sous forme d'un unique fichier .aar. Les applications basées sur Compose ou sur View fonctionnent toutes les deux ; le SDK est indépendant du framework d'interface.

Démo sur GitHub

📦

Captcha-La/android-demo — exemple complet exécutable avec chaque étape d'intégration.

Installation

Le SDK est distribué sous forme d'un unique fichier .aar que vous téléchargez depuis le tableau de bord CaptchaLa. Déposez-le dans le dossier libs/ de votre module applicatif et référencez-le depuis 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
}

Ou téléchargez l'AAR pour une intégration manuelle :

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

Téléchargement : dash.captcha.la/downloads (dernier AAR).

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

Compilez et installez la démo avec :

./gradlew installDebug

Démarrage rapide

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

Surface de l'API

Symbole	Rôle
CaptchalaClient.getClient(ctx)	Point d'entrée singleton. Renvoie le client partagé lié au contexte applicatif.
CaptchalaConfig.Builder()	Builder fluide pour appKey, action, lang, theme, enableVoice, enableOfflineMode, serverToken.
init(config)	Initialise le client avec un CaptchalaConfig construit. Peu coûteux à appeler — détruit et reconstruit l'état si rappelé.
setListener(listener)	Enregistre un CaptchalaListener pour les callbacks onReady, onSuccess, onFail, onError, onClose.
verify(activity)	Ouvre le CAPTCHA par-dessus l'Activity donnée. Le résultat est livré via le listener.
CaptchalaResult	Contient passToken, challengeId, ttl, isOffline, isClientOnly. Envoyez passToken à votre backend.
CaptchalaClient.destroy()	Démonte le singleton (libère le WebView, les handles natifs). Appelez-le depuis Activity.onDestroy si vous réinitialisez souvent.

Validation côté serveur

Transmettez result.passToken (ou result.token) à votre backend et validez-le auprès de l'API CaptchaLa. N'exposez jamais X-App-Secret dans le code client.

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

Consultez la Référence de l'API pour l'endpoint de validation complet et le flux X-App-Key / X-App-Secret.

Dépannage

• UnsatisfiedLinkError au démarrage
  Assurez-vous que vos abiFilters couvrent armeabi-v7a, arm64-v8a, x86, x86_64 afin que toutes les architectures d'appareil trouvent une bibliothèque native correspondante. Le app/build.gradle de la démo montre la liste exacte des filtres.

• ProGuard / R8 supprime les classes du SDK en release
  Ajoutez une règle « keep » pour le package du SDK, par ex. -keep class la.captcha.sdk.** { *; } et -dontwarn la.captcha.sdk.** dans votre proguard-rules.pro.

• minSdkVersion trop bas
  Le SDK requiert minSdkVersion 21 (Android 5.0). Les cibles inférieures échoueront à la compilation.

• Trafic HTTP en clair bloqué
  Votre manifeste doit comporter android:usesCleartextTraffic="false" (la démo le fait). L'endpoint CaptchaLa est HTTPS uniquement.

Prérequis

• Android 5.0+ (minSdkVersion 21)
• AndroidX (compileSdk 33+)
• Kotlin 1.8+ ou chaîne d'outils Java équivalente (Java 17 source / target)
• ABI : armeabi-v7a, arm64-v8a, x86, x86_64