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)