SDK Flutter

Plugin Flutter construit sur les SDK natifs iOS / Android, exposant un unique CaptchalaClient Dart pour les deux plateformes mobiles (avec prise en charge desktop Linux / macOS / Windows via un WebView intégré).

Démo sur GitHub

📦

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

Installation

Ajoutez le package depuis pub.dev :

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

Pour iOS / macOS, la première compilation exécute automatiquement pod install. Vérifiez que ios/Podfile déclare platform :ios, '13.0' (ou plus).

Démarrage rapide

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')),
        ]),
      ),
    );
  }
}

Surface de l'API

Symbole	Rôle
CaptchalaClient.instance	Accesseur singleton du plugin.
CaptchalaConfig(...)	Enregistrement Dart simple : appKey, action, lang, theme, enableVoice, enableOfflineMode, maskClosable, serverToken.
await client.initialize(config)	Applique la configuration. Renvoie la même instance de client pour chaîner setCallbacks.
setCallbacks(...)	Enregistre les callbacks onSuccess, onFail, onError, onClose, onServerTokenExpired.
await client.verify()	Ouvre la vue native du CAPTCHA (Android : Activity par-dessus Flutter ; iOS : UIViewController par-dessus Flutter).
CaptchalaResult	Fourni à onSuccess. Champs : passToken, challengeId, ttl, isOffline, isClientOnly.

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

• Échec de pod install sur iOS
  Dans ios/Podfile, définissez platform :ios, '13.0' (ou plus). Exécutez flutter clean && flutter pub get && cd ios && pod install après un changement de version du plugin.

• Incompatibilité de minSdkVersion sur Android
  Passez android/app/build.gradle à minSdkVersion 21. Le SDK Android natif refusera de compiler en dessous.

• Les callbacks s'exécutent sur une isolate d'arrière-plan
  Encadrez toujours setState par if (mounted) avant de modifier l'état de l'interface depuis les callbacks. La démo applique ce contrôle à chaque callback qui met à jour l'état.

• Cibles desktop (Linux / Windows / macOS)
  Linux requiert GTK3 + WebKitGTK + libcurl. Windows nécessite le runtime WebView2 d'Edge (Win 10 1809+). macOS desktop utilise automatiquement le WebView système.

Prérequis

• Flutter 3.10+ / Dart 3.0+
• Android : minSdkVersion 21 (Android 5.0+)
• iOS : 13.0+ avec CocoaPods
• Desktop (optionnel) : GTK3 + WebKitGTK sous Linux, runtime WebView2 sous Windows 10 1809+