Flutter SDK

Yerel iOS / Android SDK'ları üzerine kurulu Flutter eklentisi; her iki mobil platform için tek bir Dart CaptchalaClient sunar (gömülü WebView ile Linux / macOS / Windows masaüstü desteği dahil).

GitHub'da demo

📦

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

Kurulum

Paketi pub.dev'den ekleyin:

# pubspec.yaml
dependencies:
  captchala: ^1.3.2
  http: ^1.2.0          # used by the demo's token-fetch helpers

flutter pub get
flutter run               # auto-picks the foreground device
# or:
flutter run -d <device-id>

iOS / macOS için ilk derleme pod install'u otomatik çalıştırır. ios/Podfile dosyasının platform :ios, '13.0' (veya üstü) bildirdiğinden emin olun.

Hızlı başlangıç

import 'package:flutter/material.dart';
import 'package:captchala/captchala.dart';

class LoginScreen extends StatefulWidget {
  const LoginScreen({super.key});
  @override
  State<LoginScreen> createState() => _LoginScreenState();
}

class _LoginScreenState extends State<LoginScreen> {
  String _status = 'Tap to verify';
  bool _verifying = false;

  Future<void> _runVerify() async {
    setState(() { _verifying = true; _status = 'Fetching server_token...'; });

    // 1. Fetch a one-shot server_token from YOUR backend.
    final initialToken = await fetchServerTokenFromYourBackend();

    // 2. Build config from your business action.
    final config = CaptchalaConfig(
      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,
      maskClosable: false,
      serverToken: initialToken,
    );

    // 3. Initialize, register callbacks, then call verify().
    final client = await CaptchalaClient.instance.initialize(config);
    client.setCallbacks(
      onSuccess: (r) async {
        // Send r.passToken to YOUR backend for validation.
        if (!mounted) return;
        setState(() { _status = 'OK: ${r.passToken}'; _verifying = false; });
      },
      onFail:    (e) { if (mounted) setState(() { _status = 'fail: ${e.code}'; _verifying = false; }); },
      onError:   (e) { if (mounted) setState(() { _status = 'error: ${e.code} ${e.message}'; _verifying = false; }); },
      onClose:   () { if (mounted && _verifying) setState(() { _status = 'closed'; _verifying = false; }); },
      onServerTokenExpired: () => fetchServerTokenFromYourBackend(),
    );
    await client.verify();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Column(mainAxisSize: MainAxisSize.min, children: [
          ElevatedButton(
            onPressed: _verifying ? null : _runVerify,
            child: Text(_verifying ? 'Verifying...' : 'Verify with CAPTCHA'),
          ),
          const SizedBox(height: 12),
          Text(_status, style: const TextStyle(fontFamily: 'monospace')),
        ]),
      ),
    );
  }
}

API yüzeyi

Sembol	Amaç
CaptchalaClient.instance	Eklenti için singleton erişimcisi.
CaptchalaConfig(...)	Düz Dart kaydı: appKey, action, lang, theme, enableVoice, enableOfflineMode, maskClosable, serverToken.
await client.initialize(config)	Config'i uygular. setCallbacks ile zincirleyebilmeniz için aynı istemci örneğini döndürür.
setCallbacks(...)	onSuccess, onFail, onError, onClose, onServerTokenExpired geri çağrılarını kaydedin.
await client.verify()	Yerel CAPTCHA görünümünü açar (Android: Flutter üstünde Activity; iOS: Flutter üstünde UIViewController).
CaptchalaResult	onSuccess'e iletilir. Alanlar: passToken, challengeId, ttl, isOffline, isClientOnly.

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

• iOS pod install başarısız
  ios/Podfile içinde platform :ios, '13.0' (veya üstü) ayarlayın. Eklenti sürümünü değiştirdikten sonra flutter clean && flutter pub get && cd ios && pod install çalıştırın.

• Android minSdkVersion uyumsuzluğu
  android/app/build.gradle dosyasını minSdkVersion 21 olarak yükseltin. Native Android SDK bunun altında derlenmeyi reddeder.

• Geri çağrılar arka plan isolate'inde tetikleniyor
  Geri çağrılarda UI durumunu değiştirmeden önce setState'i her zaman if (mounted) ile koruyun. Demo, durumu güncelleyen her geri çağrıyı bu kontrolle sarar.

• Masaüstü hedefleri (Linux / Windows / macOS)
  Linux, GTK3 + WebKitGTK + libcurl gerektirir. Windows için Edge WebView2 Runtime (Win 10 1809+) gerekir. macOS masaüstü, sistem WebView'ini otomatik kullanır.

Gereksinimler

• Flutter 3.10+ / Dart 3.0+
• Android: minSdkVersion 21 (Android 5.0+)
• iOS: CocoaPods ile 13.0+
• Masaüstü (isteğe bağlı): Linux'ta GTK3 + WebKitGTK, Windows 10 1809+ üzerinde WebView2 Runtime