Android SDK

Android 5.0+ (API 21+) için Android SDK, tek bir .aar olarak paketlenmiştir. Hem Compose hem de View tabanlı uygulamalarla çalışır; SDK, UI framework'ünden bağımsızdır.

GitHub'da demo

📦

Captcha-La/android-demo — her entegrasyon adımını içeren tam çalıştırılabilir örnek.

Kurulum

SDK, CaptchaLa panelinden indirdiğiniz tek bir .aar olarak gelir. Uygulama modülünüzün libs/ klasörüne bırakın ve Gradle'dan referans verin:

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

Veya manuel entegrasyon için AAR'ı indirin:

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

İndirme: dash.captcha.la/downloads (en son AAR).

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

Demoyu derleyip kurmak için:

./gradlew installDebug

Hızlı başlangıç

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 yüzeyi

Sembol	Amaç
CaptchalaClient.getClient(ctx)	Singleton giriş noktası. Uygulama context'ine bağlı paylaşımlı istemciyi döndürür.
CaptchalaConfig.Builder()	appKey, action, lang, theme, enableVoice, enableOfflineMode, serverToken için akıcı builder.
init(config)	İstemciyi yapılandırılmış bir CaptchalaConfig ile başlatır. Tekrar çağırmak ucuzdur — durumu yıkıp yeniden kurar.
setListener(listener)	onReady, onSuccess, onFail, onError, onClose geri çağrıları için bir CaptchalaListener kaydedin.
verify(activity)	CAPTCHA'yı verilen Activity üzerinde açar. Sonuç dinleyici üzerinden iletilir.
CaptchalaResult	passToken, challengeId, ttl, isOffline, isClientOnly alanlarını tutar. passToken'ı backend'inize gönderin.
CaptchalaClient.destroy()	Singleton'ı yık (WebView'i, native handle'ları serbest bırakır). Sık yeniden init ediyorsanız Activity.onDestroy'dan çağırın.

Sunucu tarafı doğrulama

result.passToken (veya result.token) değerini backend'inize iletip CaptchaLa API'sine karşı doğrulayın. X-App-Secret değerini asla istemci kodunda açmayın.

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

Tam doğrulama uç noktası ve X-App-Key / X-App-Secret akışı için API Referansı'na bakın.

Sorun giderme

• Başlangıçta UnsatisfiedLinkError
abiFilters ayarınızın armeabi-v7a, arm64-v8a, x86, x86_64 değerlerini kapsadığından emin olun ki tüm cihaz mimarileri eşleşen bir native lib bulabilsin. Demonun app/build.gradle dosyası tam filtre listesini gösterir.

• ProGuard / R8 release'de SDK sınıflarını siliyor
  SDK paketi için bir keep kuralı ekleyin, örn. proguard-rules.pro içine -keep class la.captcha.sdk.** { *; } ve -dontwarn la.captcha.sdk.**.

• minSdkVersion çok düşük
  SDK, minSdkVersion 21 (Android 5.0) gerektirir. Daha düşük hedefler derleme zamanında başarısız olur.

• Cleartext HTTP trafiği engellendi
  Manifest'inizde android:usesCleartextTraffic="false" olmalı (demo öyledir). CaptchaLa uç noktası yalnızca HTTPS'tir.

Gereksinimler

• Android 5.0+ (minSdkVersion 21)
• AndroidX (compileSdk 33+)
• Kotlin 1.8+ veya eşdeğer Java toolchain (Java 17 source / target)
• ABI'ler: armeabi-v7a, arm64-v8a, x86, x86_64