---
title: SDK Flutter
---

# 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

::: tip 📦
[Captcha-La/flutter-demo](https://github.com/Captcha-La/flutter-demo) — exemple complet exécutable avec chaque étape d'intégration.
:::

## Installation

Ajoutez le package depuis pub.dev :

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

```bash
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

```dart
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.

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

- **É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+