Yandex SmartCaptcha for Flutter

This package makes it easy to integrate Yandex SmartCaptcha into Flutter mobile apps. To learn more about the Yandex SmartCaptcha service, visit its official page.

Motivation

One day at work, I urgently needed to integrate a Yandex CAPTCHA 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 most basic example:

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

In most cases, you’ll only need the YandexSmartCaptcha and CaptchaConfig classes. The CaptchaController is entirely optional – it is useful if you need to trigger validation, reset the widget, or destroy it programmatically.

CaptchaConfig parameters

This is an immutable configuration for Web SmartCaptcha.

The term "Web SmartCaptcha" refers to the underlying HTML page hosted inside the WebView that instantiates and executes the Yandex SmartCaptcha JavaScript widget.

Parameter	Required	Default	Description
clientKey	✔		The client-side key passed to Web SmartCaptcha.
language		ru	The language for the Web SmartCaptcha UI.
alwaysShowChallenge		false	Whether the CAPTCHA should always display a challenge. Useful for testing.
useInvisibleMode		false	Whether to run CAPTCHA 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 specialized mobile WebView optimization mode.
initialScale		1.0	The initial scale factor for the Web SmartCaptcha content.
allowUserScaling		false	Whether the user can scale the Web SmartCaptcha content using gestures.
maximumScale		3.0	The maximum scale factor when allowUserScaling is true.

YandexSmartCaptcha parameters

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

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

CaptchaController methods

Provide access to the Web SmartCaptcha's imperative methods.

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

Screenshots

1. SmartCaptcha in a simple test screen:

2. SmartCaptcha in a real-world application: