Yandex SmartCaptcha for Flutter

Static Badge

This package makes it easy to integrate Yandex SmartCaptcha into Flutter-based Android, iOS, and web apps. On Android and iOS, it uses a native WebView; on the web, it uses a DOM element and JavaScript interop. To learn more about the Yandex SmartCaptcha service, visit its official page.

Motivation

One day at work, I urgently needed to integrate Yandex SmartCaptcha into a mobile app, and the flutter_yandex_smartcaptcha package came to the rescue. However, I discovered a serious bug and reported it to the author. When they didn’t respond, I decided to create a similar package myself and learn how to publish packages on pub.flutter-io.cn in the process. End of story.

Usage

Super simple! Here’s the minimal example:

YandexSmartCaptcha(
  config: CaptchaConfig(
    clientKey: 'your-client-key',
  ),
  onChallengeSolved: (token) {
    // Handle the solved captcha token.
  },
)

In most cases, you only need the YandexSmartCaptcha and CaptchaConfig classes. CaptchaController is optional and useful when you need to trigger validation, reset the widget, or destroy it programmatically.

On mobile, ensure that the YandexSmartCaptcha's ancestor widget provides enough vertical space to accommodate both the "I'm not a robot" block and the challenge popup, as they are rendered inside a single WebView.
On the web, the ancestor widget only needs to provide enough vertical space for the "I'm not a robot" block (with a fixed height of around 100px), because Yandex fully controls the challenge popup.

Web support

You don't need to manually add the Yandex SmartCaptcha script to your index.html, as the YandexSmartCaptcha widget loads it automatically when mounted in the widget tree.

On the web, YandexSmartCaptcha hosts the Yandex SmartCaptcha JavaScript widget. Use standard layout widgets such as Center, Padding, or SizedBox to control the position of the "I'm not a robot" block. Yandex controls the challenge popup's UI and behavior (just as it does on a regular website).

The onChallengeShown/onChallengeHidden callbacks and CaptchaController methods remain fully available.

The web implementation is compatible with WebAssembly (Wasm).

CaptchaConfig parameters

This is an immutable configuration for Yandex SmartCaptcha JavaScript widget.

Ignored on web: useWebViewMode, initialScale, allowUserScaling, maximumScale.

Parameter	Required	Default	Description
`clientKey`	✔		The client-side key passed to the SmartCaptcha widget.
`language`		`ru`	The language used by the SmartCaptcha UI.
`alwaysShowChallenge`		`false`	Whether the SmartCaptcha widget should always display a challenge. Useful for testing.
`useInvisibleMode`		`false`	Whether the SmartCaptcha widget should run in invisible mode – without the "I'm not a robot" checkbox.
`badgePosition`		`bottomRight`	The position of the Data Processing Notice (DPN) badge when `useInvisibleMode` is `true`.
`hideBadge`		`false`	Whether to hide the DPN badge when `useInvisibleMode` is `true`.
`useWebViewMode`*		`true`	Whether to enable a specialized mobile WebView optimization mode.
`initialScale`*		`1.0`	The initial scale factor for the WebView content.
`allowUserScaling`*		`false`	Whether the user can scale the WebView content using gestures.
`maximumScale`*		`3.0`	The maximum scale factor when `allowUserScaling` is `true`.

YandexSmartCaptcha parameters

Control SmartCaptcha's runtime lifecycle, Flutter-level UI customization, and callback registration.

Ignored on web: backgroundColor, loadingIndicator, onNavigationRequest, baseUrl.

Parameter	Required	Default	Description
`config`	✔		The configuration for this SmartCaptcha instance.
`onChallengeSolved`	✔		Called when the user successfully solves a challenge.
`backgroundColor`*		`null`	The background color of the widget container.
`loadingIndicator`*		`null`	A custom widget displayed while SmartCaptcha script is loading.
`onCaptchaReady`		`null`	Called when the SmartCaptcha script has fully loaded and initialized.
`onChallengeShown`		`null`	Called when the SmartCaptcha challenge popup becomes visible.
`onChallengeHidden`		`null`	Called when the SmartCaptcha challenge popup is hidden.
`onTokenExpired`		`null`	Called when the SmartCaptcha token expires or is invalidated.
`onNetworkError`		`null`	Called when a network error occurs while loading or executing the SmartCaptcha widget.
`onJavaScriptError`		`null`	Called when an uncaught JavaScript error occurs inside the SmartCaptcha widget.
`onNavigationRequest`*		`null`	Called when a navigation request is made inside the WebView.
`controller`		`null`	A controller for programmatically interacting with the SmartCaptcha instance.
`baseUrl`*		`null`	An HTTP(S) base URL used for domain validation and resolving origin policy issues.

CaptchaController methods

Provide access to the SmartCaptcha widget's imperative methods.

Method	Description
`execute()`	Starts user validation.
`reset()`	Resets the SmartCaptcha widget to its initial state.
`destroy()`	Removes the SmartCaptcha widget and its associated event listeners.