GMA Flutter WebView Example

A small Flutter app demonstrating the Google Mobile Ads WebView API for Ads on both Android and iOS.

It is the cross-platform companion to:

• gamezop/gma-android-webview-example
• gma-ios-webview-example

The sample intentionally stays focused:

• One shared Flutter implementation
• A white, safe-area-aware launcher with three thumbnail cards
• One reusable WebViewController registered with Google Mobile Ads
• Correct Android and iOS media, cookie, and platform configuration
• In-app handling for off-domain ad and game click-outs
• No strict-mode or partner-security simulation

Official references

The implementation follows:

• Use WebView API for ads with Flutter
• Google Mobile Ads Flutter quick start
• Optimize WKWebView click behavior
• webview_flutter documentation

Main-screen destinations

All three destinations are active at the same time:

Card	URL	Purpose
Google WebView Ads Test	https://google.github.io/webview-ads/test/	Validate WebView settings, GMA registration, cookies, media, and clicks
Gamezop Portal	https://peslsv.play.gamezop.com	Browse the configured Gamezop portal
Random Game	https://www.gamezop.com/g/random	Resolve and launch an individual game

Edit lib/sample_destination.dart to change or extend this list.

Portal platform warnings

At the top of the launcher, the app shows a separate inline warning for each relevant platform. The portal card remains immediately available:

• iOS Simulator: App Store links cannot open in the simulator. Use a physical iPhone or iPad to test those redirects; the portal itself can still be opened.
• Android: This portal URL can crash the Android app/WebView. The red notice makes that known issue explicit before the portal is opened.

Google Mobile Ads integration

The app performs these steps in order:

1. Calls WidgetsFlutterBinding.ensureInitialized().
2. Starts native SDK initialization without blocking the launcher screen.
3. Creates a platform-aware WebViewController.
4. Enables unrestricted JavaScript.
5. Enables inline and automatic media playback.
6. Enables Android third-party cookies.
7. Installs the navigation delegate.
8. Awaits the shared SDK initialization future.
9. Calls MobileAds.instance.registerWebView(controller).
10. Loads the selected network URL.

Registration happens before the first page load. This lets AdSense code or Google Publisher Tags exchange app signals with the native GMA SDK.

This sample uses WebView-only monetization and therefore configures the integration-manager bypass instead of a native ad application ID:

Android

android/app/src/main/AndroidManifest.xml contains:

<meta-data
    android:name="com.google.android.gms.ads.INTEGRATION_MANAGER"
    android:value="webview" />

iOS

ios/Runner/Info.plist contains:

<key>GADIntegrationManager</key>
<string>webview</string>

If the application later displays native banner, interstitial, rewarded, or app-open ads, replace this WebView-only setup with the application ID required by the relevant Google Mobile Ads quick-start documentation.

WebView configuration

Shared configuration:

• JavaScript enabled
• Persistent platform website storage
• Network URLs loaded with loadRequest
• Main-document load progress and errors surfaced in Flutter
• Back gestures/history supported

Android-specific configuration:

• Third-party cookies enabled
• Media playback does not require a user gesture
• WebView debugging enabled in debug builds

iOS-specific configuration:

• Inline media playback enabled
• No media types require a user gesture
• Back/forward navigation gestures enabled

Third-party cookies are expected to be unavailable on iOS. Google’s test page reports this as informational rather than an integration failure.

Navigation and click behavior

Top-level HTTPS navigation stays embedded for:

• google.github.io
• gamezop.com
• Any host ending in .gamezop.com

The Gamezop subdomain rule matters because /g/random can redirect to a game-specific Gamezop host.

The allowlist only applies to top-level navigation. Subframes are deliberately allowed without host filtering because games, ad tags, analytics, and browser-internal documents can use:

• Additional HTTPS origins
• about:blank
• about:srcdoc
• blob: and data: documents

Filtering these frames is a common reason games stop during initialization.

Off-domain HTTPS clicks open above the game using:

• SFSafariViewController on iOS
• Custom Tabs on Android

App Store, Play Store, and custom-scheme links are handed to the operating system. Returning from a click-out preserves the original WebView and running game state.

Project structure

• lib/main.dart: SDK initialization and root app
• lib/mobile_ads_service.dart: single shared SDK initialization future
• lib/home_screen.dart: launcher and thumbnail cards
• lib/sample_destination.dart: the three URLs
• lib/navigation_policy.dart: shared allowlist
• lib/gma_webview_screen.dart: controller configuration, GMA registration, loading, and click handling
• android/app/src/main/AndroidManifest.xml: Android internet permission and GMA integration manager
• ios/Runner/Info.plist: iOS GMA integration manager
• test/: launcher and navigation-policy tests

Requirements

• Flutter 3.44.8 or later
• Dart 3.12 or later
• Android Studio with Android SDK 24 or later
• Xcode 16 or later
• CocoaPods

Package versions are locked in pubspec.lock.

Run

Install packages:

flutter pub get

Check the local toolchains:

flutter doctor

Run on Android:

flutter run -d <android-device-id>

Run on iOS:

flutter run -d <ios-device-id>

You can list available device IDs with:

flutter devices

Build and test

flutter analyze
flutter test
flutter build apk --debug
flutter build ios --simulator --debug

Google validation checklist

Open the Google WebView Ads Test card and verify:

• JavaScript is enabled
• First-party cookies work
• Video plays inline
• Video starts automatically
• Video is replayable
• The WebView is connected to the Google Mobile Ads Flutter plugin
• Google Publisher Tag is connected to GMA
• target="_top" and target="_blank" href tests open correctly
• The JavaScript window.open("_blank") test opens correctly
• Returning from a click-out does not reset the test-page counter
• Store links open the appropriate store app

The Google Play market:// test only applies to Android. Third-party cookies are not expected to work on iOS.

For network-level verification, inspect an ad request and confirm it includes a scar parameter as described in Google’s Flutter WebView documentation.

Production notes

• Complete consent collection before MobileAds.instance.initialize().
• Native-app consent is not automatically propagated to hosted web content. Coordinate the WebView consent flow with your CMP.
• Register every monetized WebViewController before loading its first page.
• Do not remove script-message handlers installed by the GMA SDK.
• Keep all production pages on HTTPS; this sample needs no cleartext/ATS exceptions.
• Review App Store and Play privacy declarations before distribution.