DEV Community

Cover image for Implementing Recaptcha V3 on Flutter | Flutter Recaptcha V3
vatana7
vatana7

Posted on

Implementing Recaptcha V3 on Flutter | Flutter Recaptcha V3

#flutter #dart #recaptcha #programming

Implementing Google reCAPTCHA v3 in Flutter (Mobile)

I spent hours debugging and researching, only to find the solution was much simpler than I thought. To save you the headache, here’s a step-by-step guide on how to integrate Google reCAPTCHA v3 into a Flutter mobile application.

Prerequisites

  • A site key from your backend (ask your backend dev or generate one yourself in the reCAPTCHA admin console).
  • Clarify with your backend whether you’re using Enterprise or Standard (v2/v3) reCAPTCHA.

Choosing the Right Package

This tutorial focuses on Standard v3.

Why You Need a Hosted HTML

Unlike browsers, Flutter apps don’t have a domain. If you try to run reCAPTCHA directly inside a WebView, the domain becomes about:blank, which Google doesn’t accept.

The trick:

  • Host a simple HTML file that loads reCAPTCHA and generates a token.
  • Load that HTML inside Flutter’s WebView.
  • Pass the generated token back into Flutter.

👉 You can self-host this HTML template or use the demo page at https://emerald-eran-52.tiiny.site.
I recommend self-hosting so you’re not dependent on a third-party site.

⚠️ Don’t forget to whitelist your hosted domain in the Google reCAPTCHA admin console, otherwise tokens will always be invalid.

Step 1: Initialize Your Site Key

Place this in your app initialization (e.g. main.dart):

RecaptchaHandler.instance.setupSiteKey( dataSiteKey: AppConstants.dataSiteKey, );
Enter fullscreen mode Exit fullscreen mode

Step 2: Add the Hidden WebView

In your widget tree, include a hidden ReCaptchaWebView that points to your hosted HTML:

SizedBox( width: 1, height: 1, child: Opacity( opacity: 0.01, // don’t set 0 (may cull rendering) child: IgnorePointer( ignoring: true, child: ReCaptchaWebView( width: 1, height: 1, url: selfHostedRecaptchaHtml, // e.g. https://yourdomain.com/recaptcha.html onTokenReceived: _onTokenReceived, ), ), ), );
Enter fullscreen mode Exit fullscreen mode

Handle tokens like this:

void _onTokenReceived(String token) { // Do something with the token (e.g. send to backend) print("Got reCAPTCHA token: $token"); }
Enter fullscreen mode Exit fullscreen mode

Step 3: Trigger reCAPTCHA Execution

Whenever you need a fresh token (e.g. on registration, OTP, etc.), call:

RecaptchaHandler.executeV3(action: 'register');
Enter fullscreen mode Exit fullscreen mode

This triggers grecaptcha.execute() inside your hosted HTML, which passes the token back to Flutter via the WebView → _onTokenReceived.

Wrap-Up

And that’s it — your Flutter app can now generate Google reCAPTCHA v3 tokens!

✅ Key takeaways:

  • Know if your backend is Enterprise or Standard.
  • Always whitelist your HTML domain in Google’s console.
  • Self-host the HTML for reliability.

With this setup, you’ll have a secure and smooth reCAPTCHA v3 flow running natively in your Flutter mobile app.

Top comments (0)