---
title: SDK Android
---

# SDK Android

SDK Android para **Android 5.0+ (API 21+)**, empacotado como um único `.aar`. Funciona tanto em aplicativos baseados em Compose quanto em View; o SDK é agnóstico de framework de UI.

## Demonstração no GitHub

::: tip 📦
[Captcha-La/android-demo](https://github.com/Captcha-La/android-demo) — exemplo executável completo com cada passo de integração.
:::

## Instalação

O SDK é distribuído como um único `.aar` que você baixa no [painel da CaptchaLa](https://dash.captcha.la). Coloque-o na pasta `libs/` do módulo do seu app e referencie-o a partir do 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 baixe o AAR para integração manual:

```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](https://dash.captcha.la/downloads) (AAR mais recente).

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

Compile e instale a demo com:

```bash
./gradlew installDebug
```

## Início rápido

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

## Superfície da API

| Símbolo | Função |
| --- | --- |
| `CaptchalaClient.getClient(ctx)` | Ponto de entrada singleton. Devolve o cliente compartilhado vinculado ao contexto da aplicação. |
| `CaptchalaConfig.Builder()` | Builder fluente para `appKey`, `action`, `lang`, `theme`, `enableVoice`, `enableOfflineMode`, `serverToken`. |
| `init(config)` | Inicializa o cliente com um `CaptchalaConfig` construído. Barato de chamar — destrói e reconstrói o estado se invocado novamente. |
| `setListener(listener)` | Registra um `CaptchalaListener` para os callbacks `onReady`, `onSuccess`, `onFail`, `onError`, `onClose`. |
| `verify(activity)` | Abre o CAPTCHA por cima da Activity fornecida. O resultado é entregue via listener. |
| `CaptchalaResult` | Contém `passToken`, `challengeId`, `ttl`, `isOffline`, `isClientOnly`. Envie `passToken` ao seu backend. |
| `CaptchalaClient.destroy()` | Encerra o singleton (libera WebView, handles nativos). Chame em `Activity.onDestroy` se reinicializar com frequência. |

## Validação no servidor

Encaminhe `result.passToken` (ou `result.token`) ao seu backend e valide-o contra a API da CaptchaLa. Nunca exponha `X-App-Secret` em código de cliente.

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

Veja a [Referência da API](/pt-BR/api-reference) para o endpoint completo de validação e o fluxo `X-App-Key` / `X-App-Secret`.

## Solução de problemas

- **`UnsatisfiedLinkError` na inicialização**  
  Garanta que seus `abiFilters` cubram `armeabi-v7a`, `arm64-v8a`, `x86`, `x86_64` para que todos os formatos de dispositivo encontrem uma biblioteca nativa compatível. O `app/build.gradle` da demo mostra a lista exata de filtros.

- **ProGuard / R8 removem classes do SDK no release**  
  Adicione uma regra de keep para o pacote do SDK, ex.: `-keep class la.captcha.sdk.** { *; }` e `-dontwarn la.captcha.sdk.**` no seu `proguard-rules.pro`.

- **`minSdkVersion` baixo demais**  
  O SDK requer `minSdkVersion 21` (Android 5.0). Alvos menores falham na compilação.

- **Tráfego HTTP em texto puro bloqueado**  
  Seu manifest deve ter `android:usesCleartextTraffic="false"` (a demo tem). O endpoint da CaptchaLa é exclusivamente HTTPS.

## Requisitos

- Android 5.0+ (`minSdkVersion 21`)
- AndroidX (`compileSdk` 33+)
- Kotlin 1.8+ ou toolchain Java equivalente (Java 17 source / target)
- ABIs: `armeabi-v7a`, `arm64-v8a`, `x86`, `x86_64`