---
title: SDK Android
---

# 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

::: tip 📦
[Captcha-La/android-demo](https://github.com/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](https://dash.captcha.la). Déposez-le dans le dossier `libs/` de votre module applicatif et référencez-le depuis 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
}
```

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

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

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

```xml
<!-- 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 :

```bash
./gradlew installDebug
```

## Démarrage rapide

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

## 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.

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

Consultez la [Référence de l'API](../api-reference) 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`