captchala

Captchala SDK for Flutter — risk-driven captcha verification with native UI on iOS / Android / macOS / Linux / Windows.

Install

flutter pub add captchala

Quick start

import 'package:captchala/captchala.dart';

final config = CaptchalaConfig(
  appKey: 'your_app_key',  // get yours at https://dash.captcha.la
  serverToken: serverTokenFromYourBackend,
  lang: 'zh-CN',
  theme: 'light',
);

final client = await CaptchalaClient.instance.initialize(config);
client.setCallbacks(
  onSuccess: (result) {
    // Send result.passToken to your backend for validation
    print('pass_token: ${result.passToken}');
  },
  onError: (err) => print('error: ${err.code} ${err.message}'),
);
await client.verify();

See the example/ directory for a complete demo app.

Getting your appKey

  1. Sign in at dash.captcha.la
  2. Create an app → copy the appKey
  3. Set up your backend to issue server_token via Captchala server API (see captcha.la/docs)

Integration flow

Your Backend                    Your Flutter App                 Captchala
     |                               |                              |
     |  1. Issue server_token        |                              |
     | <---------------------------> |                              |
     |                               |                              |
     |     2. CaptchalaClient.verify(serverToken)                   |
     |                               | ─── encrypted ticket ──────> |
     |                               | <── captcha challenge ────── |
     |                               |     (native UI opens)        |
     |                               |                              |
     |     3. User completes captcha |                              |
     |                               | ─── pass_token ────────────> |
     |                               |                              |
     |  4. Validate pass_token       |                              |
     | <---------------------------> |                              |

API

See full reference at captcha.la/docs/sdk/flutter.

CaptchalaConfig

Field Type Required Default Description
appKey String Yes — Get at dash.captcha.la
serverToken String? Yes* — One-time token from your backend
action String No "default" Business action (e.g. "login")
lang String No "zh-CN" UI language
theme String No "light" "light", "dark", or "system"
enableVoice bool No true Voice accessibility fallback
enableOfflineMode bool No false Fallback when servers unreachable
maskClosable bool No false Allow dismiss by tapping outside
account String? No — User identifier for risk scoring

* Required when your app is configured to require a server-issued token (see dash.captcha.la).

CaptchalaClient

  • CaptchalaClient.instance.initialize(config) — create / reuse a client
  • client.setCallbacks(onSuccess:, onFail:, onError:, onClose:, onServerTokenExpired:) — wire UI callbacks
  • client.verify() — start the verification flow (native UI opens)
  • client.dismiss() — programmatically close the captcha
  • client.setServerToken(token) — update server token (refresh)
  • client.destroy() — release native resources

Result

onSuccess delivers a CaptchalaResult:

class CaptchalaResult {
  final String passToken;      // Submit to your backend for validation
  final String challengeId;    // Challenge identifier
  final int ttl;               // Token validity in seconds
  final bool isOffline;        // true if verified offline
  final bool isClientOnly;     // true if client-only verification
}

Platform support

Platform Minimum
iOS 13.0+
Android 5.0+ (API 21+)
macOS 10.15+
Linux Standard desktop libraries (GTK + libcurl)
Windows Windows 10 (build 1809+)

License

MIT — see LICENSE.

Libraries

captchala