bitcaptcha_flutter

Flutter widgets for BitCaptcha, the human verification service by Xinghui Shudun. Four verification types, inline or as a dialog, with the same interaction and result states as the Web / H5 / WeChat Mini Program SDKs. Runs on iOS, Android, Web and desktop.

Smart invisible check (BitCaptchaSense): one tap. Trusted users pass right away, suspicious requests fall back to a visual challenge.
Slide puzzle (BitCaptcha): drag the piece into the gap.
Text click (BitCaptchaText): tap the characters in the order shown.
Icon click (BitCaptchaText(icon: true)): tap the icons in the order shown.

Full integration guide, parameters and error codes (Chinese): shudun.bitbeam.cn/docs/captcha/#flutter

Install

dependencies:
  bitcaptcha_flutter: ^0.6.2

Create a site in the console to get a captcha_id (client side) and a secret_key (backend only).

Usage

import 'package:bitcaptcha_flutter/bitcaptcha_flutter.dart';

// Smart invisible check (recommended)
BitCaptchaSense(
  captchaId: 'YOUR_CAPTCHA_ID',
  apiBase: 'https://shudun.bitbeam.cn',
  onVerify: (r) => login(captcha: r.validate),
)

// Slide puzzle, inline
BitCaptcha(
  captchaId: 'YOUR_CAPTCHA_ID',
  apiBase: 'https://shudun.bitbeam.cn',
  onVerify: (r) => login(captcha: r.validate),
)

// Text click / icon click
BitCaptchaText(captchaId: '...', apiBase: '...', onVerify: (r) => login(captcha: r.validate))
BitCaptchaText(captchaId: '...', apiBase: '...', icon: true, onVerify: (r) => login(captcha: r.validate))

// Dialog: returns null when the user closes it
final r = await showBitCaptcha(context, captchaId: 'YOUR_CAPTCHA_ID', apiBase: 'https://shudun.bitbeam.cn');
if (r != null) login(captcha: r.validate);
// Dialog for text / icon click: showBitCaptchaText(context, ..., icon: true)

r.validate is a one-time ticket. Send it to your backend together with the business request.

Verify on your backend (required)

A client-side pass only means a ticket was issued; the security boundary is your server. Your backend calls POST https://shudun.bitbeam.cn/api/v1/captcha/verify with the validate ticket and your secret_key, and proceeds only when result is true. A ticket can be redeemed once and expires after 180 seconds. Never ship secret_key inside the app.

Parameters

Parameter	Default	Description
`captchaId` / `apiBase`	required	Site id / API origin (https required, localhost excepted)
`onVerify`	required	Called on success with `r.validate` / `r.token` / `r.captchaId`
`onError`	-	Receives a `BitCaptchaException`; `code` is network / server / rate_limited / cooldown / quota_exceeded / http. On rate limits the widget counts down and retries by itself
`fluid` / `width`	true / 320	Fill the parent width, clamped to `minWidth` / `maxWidth` (280 / 400); `fluid: false` uses the fixed `width`
`enhanced`	true	Enhanced click challenge; `BitCaptchaText` only
`icon`	false	`true` for icon click; `BitCaptchaText` / `showBitCaptchaText` only
`theme`	light	`const BitCaptchaTheme.dark()`, or `BitCaptchaTheme(primary: ..., ...)`
`lang` / `i18n`	auto / -	Built-in zh-CN / zh-TW / en / ja / ko; `auto` follows the system locale; `i18n` overrides strings by key
`maxErrors`	5	After this many consecutive failures the panel collapses and asks for a refresh; not on the invisible check
`lazy`	true	Inline widgets fetch the challenge once scrolled near the viewport; immediate when not inside a scrollable
`title`	-	Dialog title; `showBitCaptcha` / `showBitCaptchaText` only

License

MIT