ad_flow - Professional AdMob Integration for Flutter

A production-ready, fully compliant AdMob integration package for Flutter with GDPR, US Privacy, and iOS ATT support.

✨ Features

📦 Installation

1. Add Dependency

# pubspec.yaml
dependencies:
  ad_flow: ^1.3.8

2. Android Setup

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

<manifest>
    <application>
        <!-- AdMob App ID -->
        <meta-data
            android:name="com.google.android.gms.ads.APPLICATION_ID"
            android:value="ca-app-pub-XXXXXXXXXXXXXXXX~XXXXXXXXXX"/>
    </application>
</manifest>

3. iOS Setup

<!-- AdMob App ID -->
<key>GADApplicationIdentifier</key>
<string>ca-app-pub-XXXXXXXXXXXXXXXX~XXXXXXXXXX</string>

<!-- App Tracking Transparency -->
<key>NSUserTrackingUsageDescription</key>
<string>This identifier will be used to deliver personalized ads to you.</string>

<!-- SKAdNetwork IDs (required for iOS 14+) -->
<key>SKAdNetworkItems</key>
<array>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>cstr6suwn9.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>4fzdc2evr5.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>4pfyvq9l8r.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>2fnua5tdw4.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>ydx93a7ass.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>5a6flpkh64.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>p78aez3dza.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>v72qych5uu.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>c6k4g5qg8m.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>s39g8k73mm.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>3qy4746246.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>3sh42y64q3.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>f38h382jlk.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>hs6bdukanm.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>prcb7njmu6.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>wzmmz9fp6w.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>yclnxrl5pm.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>7ug5zh24hu.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>9rd848q2bz.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>n6fk4nfna4.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>kbd757ywx3.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>9t245vhmpl.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>4468km3ulz.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>m8dbw4sv7c.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>zmvfpc5aq8.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>ejvt5qm6ak.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>5lm9lj6jb7.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>44jx6755aq.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>t38b2kh725.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>24t9a8vw3c.skadnetwork</string>
    </dict>
</array>

🚀 Quick Start

⚠️ Important: Initialize Only ONCE

AdFlow is a singleton - you only need to initialize it once for your entire app, typically on your first screen (splash or home page). All other pages can simply use AdFlow.instance to show ads.

┌─────────────────────────────────────────────────────────────┐
│  YOUR APP                                                    │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐   │
│  │   Page 1     │    │   Page 2     │    │   Page 3     │   │
│  │  (Splash)    │    │   (Home)     │    │  (Details)   │   │
│  │              │    │              │    │              │   │
│  │ initialize() │───▶│ showBanner() │───▶│ showBanner() │   │
│  │    ✅        │    │     ✅        │    │     ✅        │   │
│  └──────────────┘    └──────────────┘    └──────────────┘   │
│         │                    │                    │          │
│         └────────────────────┴────────────────────┘          │
│                              │                               │
│                    ┌─────────▼─────────┐                    │
│                    │    AdFlow      │                    │
│                    │    (Singleton)    │                    │
│                    │                   │                    │
│                    │  • BannerManager  │                    │
│                    │  • Interstitial   │                    │
│                    │  • AppOpenAd      │                    │
│                    │  • Consent        │                    │
│                    └───────────────────┘                    │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Initialize in main.dart

import 'package:flutter/material.dart';
import 'package:ad_flow/ad_flow.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize AdMob with your ad unit IDs
  await AdFlow.instance.initialize(
    config: AdFlowConfig(
      // Your production ad unit IDs from AdMob console
      androidBannerAdUnitId: 'ca-app-pub-YOUR_ID/BANNER_ID',
      iosBannerAdUnitId: 'ca-app-pub-YOUR_ID/BANNER_ID',
      androidInterstitialAdUnitId: 'ca-app-pub-YOUR_ID/INTERSTITIAL_ID',
      iosInterstitialAdUnitId: 'ca-app-pub-YOUR_ID/INTERSTITIAL_ID',
      androidRewardedAdUnitId: 'ca-app-pub-YOUR_ID/REWARDED_ID',
      iosRewardedAdUnitId: 'ca-app-pub-YOUR_ID/REWARDED_ID',
      androidAppOpenAdUnitId: 'ca-app-pub-YOUR_ID/APP_OPEN_ID',
      iosAppOpenAdUnitId: 'ca-app-pub-YOUR_ID/APP_OPEN_ID',
      androidNativeAdUnitId: 'ca-app-pub-YOUR_ID/NATIVE_ID',
      iosNativeAdUnitId: 'ca-app-pub-YOUR_ID/NATIVE_ID',
    ),
    onComplete: (canRequestAds) {
      debugPrint('Ads ready: $canRequestAds');
    },
  );

  runApp(const MyApp());
}

Initialization Parameters

Advanced Initialization

// Full control over initialization
await AdFlow.instance.initialize(
  config: AdFlowConfig(
    androidBannerAdUnitId: 'ca-app-pub-YOUR_ID/BANNER_ID',
    iosBannerAdUnitId: 'ca-app-pub-YOUR_ID/BANNER_ID',
    // ... other ad unit IDs
  ),
  onComplete: (canRequestAds) {
    debugPrint('Ads ready: $canRequestAds');
  },
  preloadInterstitial: true,       // Preload interstitial for faster display
  preloadRewarded: true,           // Preload rewarded for faster display
  preloadAppOpen: true,            // Preload app open ad
  showAppOpenOnColdStart: true,    // Show ad on first app launch
  enableAppOpenOnForeground: true, // Show ad when returning to app
  maxForegroundAdsPerSession: 2,   // Allow 2 foreground app open ads
);

Test Mode (Development)

// For development/testing, use test mode:
await AdFlow.instance.initialize(
  config: AdFlowConfig.testMode(), // Uses Google's test ad IDs
);

📱 Usage Examples

Banner Ads (Easiest Way)

import 'package:ad_flow/ad_flow.dart';

// Just drop this widget anywhere!
@override
Widget build(BuildContext context) {
  return Scaffold(
    body: YourContent(),
    
    // One line for a banner ad:
    bottomNavigationBar: const EasyBannerAd(),
  );
}

Banner Ads (With More Control)

class MyPage extends StatefulWidget {
  @override
  State<MyPage> createState() => _MyPageState();
}

class _MyPageState extends State<MyPage> {
  final BannerAdManager _bannerManager = BannerAdManager();

  @override
  void initState() {
    super.initState();
    _loadBanner();
  }

  Future<void> _loadBanner() async {
    await _bannerManager.loadAdaptiveBanner(
      context: context,
      onAdLoaded: (ad) => setState(() {}),
      onAdFailedToLoad: (ad, error) {
        debugPrint('Banner failed: ${error.message}');
      },
    );
  }

  @override
  void dispose() {
    _bannerManager.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: YourContent(),
      bottomNavigationBar: _bannerManager.isLoaded
          ? _bannerManager.buildAdWidget()
          : const SizedBox.shrink(),
    );
  }
}

Collapsible Banner Ads

// Using EasyBannerAd widget
const EasyBannerAd(collapsible: true)

// Or with BannerAdManager
await _bannerManager.loadCollapsibleBanner(
  context: context,
  placement: CollapsibleBannerPlacement.bottom, // or .top
  onAdLoaded: (ad) => setState(() {}),
);

Custom Size Banner Ads

// Load a specific size banner (great for dialogs)
await _bannerManager.loadBanner(
  size: AdSize.mediumRectangle, // 300x250
  onAdLoaded: (ad) => setState(() {}),
);

// Other common sizes:
// AdSize.banner           // 320x50
// AdSize.largeBanner      // 320x100
// AdSize.mediumRectangle  // 300x250 (best for dialogs)
// AdSize.fullBanner       // 468x60
// AdSize.leaderboard      // 728x90

Interstitial Ads

// Show interstitial (auto-preloaded on init)
await AdFlow.instance.interstitial.showAd(
  onAdDismissed: () {
    // Continue with your app
    Navigator.pushNamed(context, '/nextScreen');
  },
  onAdFailedToShow: () {
    // Ad not ready, proceed anyway
    Navigator.pushNamed(context, '/nextScreen');
  },
);

// Check if ready before showing
if (AdFlow.instance.interstitial.isLoaded) {
  AdFlow.instance.interstitial.showAd();
}

Interstitial with Frequency Control

int _actionCount = 0;

void _onUserAction() {
  _actionCount++;
  
  // Show interstitial every 5 actions
  if (_actionCount % 5 == 0) {
    if (AdFlow.instance.interstitial.isLoaded) {
      AdFlow.instance.interstitial.showAd();
    }
  }
}

Rewarded Ads

Rewarded ads let users watch video ads in exchange for in-app rewards (coins, extra lives, etc.):

// Load a rewarded ad (usually done at app start or before needed)
await AdFlow.instance.rewarded.loadAd(
  onAdLoaded: (ad) {
    print('Rewarded ad ready!');
  },
  onAdFailedToLoad: (error) {
    print('Failed to load rewarded ad: ${error.message}');
  },
);

// Show the rewarded ad when user clicks "Watch Ad" button
await AdFlow.instance.rewarded.showAd(
  onUserEarnedReward: (reward) {
    // Grant the reward to the user
    setState(() {
      _userCoins += reward.amount.toInt();
    });
    print('User earned ${reward.amount} ${reward.type}');
  },
  onAdDismissed: () {
    // Ad closed (whether reward earned or not)
    print('Rewarded ad dismissed');
  },
  onAdFailedToShow: () {
    // Ad not available
    ScaffoldMessenger.of(context).showSnackBar(
      const SnackBar(content: Text('No reward available. Try again later!')),
    );
  },
);

Preload Rewarded Ad on Init

// Add to your initialization for faster ad display
await AdFlow.instance.initialize(
  config: AdFlowConfig(...),
  preloadRewarded: true,  // Preload rewarded ad
);

Check Load Status & Listen for Changes

// Check if rewarded ad is ready
if (AdFlow.instance.rewarded.isLoaded) {
  // Show "Watch Ad" button
  ElevatedButton(
    onPressed: _watchAdForReward,
    child: const Text('Watch Ad for 50 Coins'),
  );
}

// Listen for ad load status changes (for reactive UI)
@override
void initState() {
  super.initState();
  AdFlow.instance.rewarded.addStatusListener(_onAdStatusChanged);
}

void _onAdStatusChanged() {
  setState(() {}); // Rebuild UI when ad loads/changes
}

@override
void dispose() {
  AdFlow.instance.rewarded.removeStatusListener(_onAdStatusChanged);
  super.dispose();
}

Manual Reload After Showing

// Rewarded ads auto-reload after being shown, but you can also manually reload:
if (!AdFlow.instance.rewarded.isLoaded && 
    !AdFlow.instance.rewarded.isLoading) {
  await AdFlow.instance.rewarded.loadAd();
}

App Open Ads

App open ads are automatically handled when you set enableAppOpenOnForeground: true during initialization. They show when the user brings your app to the foreground.

// Manual control (if needed)
if (AdFlow.instance.appOpen.isAdAvailable) {
  await AdFlow.instance.appOpen.showAdIfAvailable(
    onAdDismissed: () {
      // App resumed
    },
  );
}

Privacy Settings Button

// Check if user needs privacy options (GDPR regions)
if (AdFlow.instance.isPrivacyOptionsRequired) {
  IconButton(
    icon: const Icon(Icons.privacy_tip),
    onPressed: () {
      AdFlow.instance.showPrivacyOptions(
        onComplete: () {
          // User updated privacy settings
        },
      );
    },
  );
}

Ad Inspector (Debug Mode)

// Open the Ad Inspector for debugging
AdFlow.instance.openAdInspector();

Remove Ads (In-App Purchase)

Built-in support for "Remove Ads" purchases:

// After successful IAP purchase
await AdFlow.instance.disableAds();

// All ad widgets automatically hide!
// EasyBannerAd, EasyNativeAd, etc. respect this setting.

// Check if ads are enabled
if (AdFlow.instance.isAdsEnabled) {
  // Show ads
}

// Re-enable ads (e.g., restore purchase failed)
await AdFlow.instance.enableAds();

// Reactive UI with StreamBuilder
StreamBuilder<bool>(
  stream: AdFlow.instance.adsEnabledStream,
  builder: (context, snapshot) {
    final adsEnabled = snapshot.data ?? true;
    if (!adsEnabled) return const SizedBox.shrink();
    return const EasyBannerAd();
  },
)

Error Handling

Centralized error handling for all ad operations:

// Stream-based (recommended for reactive apps)
AdFlow.instance.errorStream.listen((error) {
  print('Ad error: ${error.type} - ${error.message}');
  
  // Log to analytics
  analytics.logEvent('ad_error', {
    'type': error.type.name,      // bannerLoad, interstitialLoad, etc.
    'code': error.code,           // Error code from SDK
    'message': error.message,     // Human-readable message
    'adUnitId': error.adUnitId,   // Which ad unit failed
  });
});

// Callback-based (simpler alternative)
AdFlow.instance.setErrorCallback((error) {
  crashlytics.recordError(error.originalError ?? error.message);
});

// Clear callback when done
AdFlow.instance.clearErrorCallback();

Error Types:

Native Ads Setup

Native ads require platform-specific factory code. See the full guide:

📖 Native Ads Setup Guide

Quick overview:

1. Create native ad factories (Kotlin for Android, Swift for iOS)
2. Register factories in MainActivity.kt / AppDelegate.swift
3. Create layout XML (Android) or XIB files (iOS)
4. Use in Flutter with factoryId

// Load native ad
await AdFlow.instance.native.loadAd(
  factoryId: 'medium_template',  // Must match registered factory
  onAdLoaded: (ad) => setState(() {}),
);

// Display
if (AdFlow.instance.native.isLoaded) {
  SizedBox(
    height: 300,
    child: AdWidget(ad: AdFlow.instance.native.nativeAd!),
  )
}

Privacy Settings Button (GDPR Requirement)

GDPR requires providing users a way to modify their consent. Use these widgets in your settings screen:

// Simple button - auto shows/hides based on GDPR requirement
EasyPrivacySettingsButton()

// With custom text
EasyPrivacySettingsButton(
  text: 'Manage Privacy',
  icon: Icons.shield,
)

// For settings screens - ListTile version
PrivacySettingsListTile(
  title: 'Privacy Settings',
  subtitle: 'Manage your ad preferences',
)

// Always visible (ignores GDPR check)
PrivacySettingsListTile(
  alwaysShow: true,
)

// Fully custom widget
EasyPrivacySettingsButton(
  child: YourCustomWidget(),
  onFormDismissed: () {
    print('User updated privacy settings');
  },
)

📂 Package Structure

lib/
├── ad_flow.dart                    # Barrel export (import this)
└── src/
    ├── ad_config.dart              # Configuration & ad unit IDs
    ├── ad_error_handler.dart       # Centralized error handling
    ├── ad_service.dart             # Main AdFlow service (singleton)
    ├── ads_enabled_manager.dart    # Remove Ads feature
    ├── consent_manager.dart        # GDPR/ATT consent handling
    ├── consent_explainer_dialog.dart   # Pre-consent explainer dialogs
    ├── consent_explainer_localizations.dart # Multi-language support
    ├── banner_ad_manager.dart      # Banner ad management
    ├── easy_banner_widget.dart     # Drop-in banner widget
    ├── easy_privacy_settings_button.dart # GDPR privacy settings button
    ├── interstitial_ad_manager.dart    # Interstitial ad management
    ├── rewarded_ad_manager.dart    # Rewarded ad management
    ├── app_open_ad_manager.dart    # App open ad management
    ├── app_lifecycle_reactor.dart  # App state monitoring
    ├── native_ad_manager.dart      # Native ad management
    └── native_ad_widget.dart       # Drop-in native ad widgets

⚙️ Configuration

Behavior Settings

Customize ad behavior via AdFlowConfig:

await AdFlow.instance.initialize(
  config: AdFlowConfig(
    // Your ad unit IDs...
    androidBannerAdUnitId: 'ca-app-pub-xxx/xxx',
    iosBannerAdUnitId: 'ca-app-pub-xxx/xxx',
    
    // Behavior settings
    appOpenAdMaxCacheDuration: Duration(hours: 4), // Google recommends max 4 hours
    minInterstitialInterval: Duration(seconds: 30), // Cooldown between interstitials
    maxLoadRetries: 3,                              // Retry failed loads
    retryDelay: Duration(seconds: 5),               // Delay between retries
    
    // Testing & debug
    testDeviceIds: ['YOUR_DEVICE_HASHED_ID'],       // Avoid invalid impressions
    enableConsentDebug: false,                       // Test GDPR in non-EU regions
  ),
);

Test Device IDs

Add your test device ID to avoid invalid impressions during development:

config: AdFlowConfig(
  // ... ad unit IDs
  testDeviceIds: ['YOUR_DEVICE_HASHED_ID'],
),

Find your device ID in the console logs:

I/Ads: Use RequestConfiguration.Builder().setTestDeviceIds(Arrays.asList("YOUR_DEVICE_ID"))

🔒 Privacy & Compliance

GDPR (Europe)

• ✅ Automatically shows consent form for EU/UK/Switzerland users
• ✅ Uses Google's certified UMP SDK
• ✅ Stores consent for future sessions
• ✅ Respects user's privacy choices

US Privacy (CCPA)

• ✅ Supports US state privacy regulations
• ✅ Handles opt-out requests

iOS ATT (App Tracking Transparency)

• ✅ Integrated with consent flow
• ✅ Shows system permission dialog
• ✅ Respects user's tracking choice

How It Works

App Start
    │
    ▼
┌─────────────────────┐
│ Check Consent Status │
└─────────────────────┘
    │
    ▼ (if GDPR region)
┌─────────────────────┐
│ Show Consent Form   │
└─────────────────────┘
    │
    ▼ (if iOS)
┌─────────────────────┐
│ ATT Permission      │
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│ Initialize Ads SDK  │
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│ Preload Ads         │
└─────────────────────┘

Pre-Consent Explainer (Better UX)

For a friendlier user experience, you can show an explainer dialog before the official consent popups appear. This gives users context about why they're being asked for consent.

// Option 1: Initialize with explainer (recommended for better UX)
class _MyHomePageState extends State<MyHomePage> {
  @override
  void initState() {
    super.initState();
    // Show explainer after first frame renders
    WidgetsBinding.instance.addPostFrameCallback((_) {
      AdFlow.instance.initializeWithExplainer(
        context: context,
        onComplete: (canRequestAds) {
          debugPrint('Ads ready: $canRequestAds');
        },
      );
    });
  }
}

// Option 2: Standard initialization (consent popups appear immediately)
await AdFlow.instance.initialize(
  onComplete: (canRequestAds) {
    // Ready
  },
);

The explainer shows:

• 🎯 General privacy explainer - "Your Privacy Matters" with benefits
• 📱 iOS ATT explainer - Brief explanation before the system ATT popup

You can also show the dialogs manually:

// Show the general consent explainer
await ConsentExplainerDialog.show(context);

// Show the iOS ATT explainer (iOS only)
await ATTExplainerDialog.show(context);

Multi-Language Support

Built-in localized texts for consent explainers:

// Use pre-defined language texts
AdFlow.instance.initializeWithExplainer(
  context: context,
  consentTexts: kPersianConsentExplainerTexts,
  attTexts: kPersianATTExplainerTexts,
  onComplete: (canRequestAds) {
    debugPrint('Ads ready: $canRequestAds');
  },
);

// Or get texts by language code
final (consentTexts, attTexts) = getExplainerTextsForLanguage('es');

AdFlow.instance.initializeWithExplainer(
  context: context,
  consentTexts: consentTexts,
  attTexts: attTexts,
);

// Create custom texts for any language
const myCustomTexts = ConsentExplainerTexts(
  title: 'Your Title',
  description: 'Your description...',
  benefitRelevantAds: 'Relevant ads',
  benefitDataSecure: 'Data stays secure',
  benefitKeepFree: 'Keeps app free',
  settingsHint: 'Change anytime in Settings.',
  continueButton: 'Continue',
  skipButton: 'Decide later',
);

💰 Revenue Optimization Tips

1. Ad Placement Best Practices

2. Interstitial Frequency

// Default cooldown is 30 seconds (configurable via AdFlowConfig)
// Recommended: Show at natural breaks, not too frequently
minInterstitialInterval: Duration(seconds: 30),

3. Banner Refresh

Banners automatically refresh every 60 seconds (AdMob default). Don't manually refresh more frequently.

4. Fill Rate Optimization

• ✅ Use adaptive banners (auto-sizes)
• ✅ Keep HTTP timeout at 30 seconds
• ✅ Implement retry logic (included)
• ✅ Test on real devices

5. eCPM Optimization

• ✅ Enable all ad formats
• ✅ Use mediation (see below)
• ✅ Target appropriate content rating
• ✅ Maintain high user engagement

🔗 Mediation Support

Maximize revenue by serving ads from multiple networks. ad_flow supports Unity Ads, AppLovin, and any other AdMob mediation network.

Quick Setup

import 'package:ad_flow/ad_flow.dart';
import 'package:gma_mediation_unity/gma_mediation_unity.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  // Register BEFORE AdFlow.initialize()
  final unity = GmaMediationUnity();
  MediationHelper.registerUnityWithCallbacks(
    setGDPRConsent: unity.setGDPRConsent,
    setCCPAConsent: unity.setCCPAConsent,
  );

  // Consent is auto-forwarded during initialization
  await AdFlow.instance.initialize(...);
}

📖 Full guide: See doc/MEDIATION_SETUP.md for complete setup instructions, supported networks, and troubleshooting.

🔍 API Reference

AdFlow

// Singleton instance
AdFlow.instance

// Properties
bool isInitialized              // SDK initialized?
bool isMobileAdsInitialized     // Mobile Ads ready?
bool isPrivacyOptionsRequired   // Show privacy button?
bool isAdsEnabled               // Ads enabled? (Remove Ads)
bool isAdsDisabled              // Ads disabled?

// Managers
ConsentManager consent          // Consent handling
BannerAdManager banner          // Banner ads
InterstitialAdManager interstitial  // Interstitial ads
RewardedAdManager rewarded      // Rewarded ads
AppOpenAdManager appOpen        // App open ads
NativeAdManager native          // Native ads

// Methods
Future<void> initialize({...})  // Initialize everything
Future<void> disableAds()       // Disable ads (Remove Ads)
Future<void> enableAds()        // Re-enable ads
void showPrivacyOptions({...})  // Show privacy form
void openAdInspector()          // Debug tool

// Streams
Stream<bool> adsEnabledStream   // Reactive ads enabled state

BannerAdManager

// Properties
bool isLoaded                   // Banner ready?
bool isLoading                  // Loading in progress?
BannerAd? bannerAd             // The ad object

// Methods
Future<void> loadAdaptiveBanner({...})    // Load adaptive banner
Future<void> loadCollapsibleBanner({...}) // Load collapsible banner
Widget? buildAdWidget()                    // Get AdWidget
void dispose()                             // Clean up

InterstitialAdManager

// Properties
bool isLoaded                   // Ad ready?
bool isLoading                  // Loading in progress?
bool isShowing                  // Currently displayed?
bool canShowAd                  // Cooldown passed?

// Methods
Future<void> loadAd({...})     // Load interstitial
Future<bool> showAd({...})     // Show interstitial
void dispose()                  // Clean up

AppOpenAdManager

// Properties
bool isLoaded                   // Ad loaded?
bool isAdAvailable             // Ready & not expired?

// Methods
Future<void> loadAd({...})           // Load app open ad
Future<void> showAdIfAvailable({...}) // Show if available
void dispose()                        // Clean up

RewardedAdManager

// Properties
bool isLoaded                   // Ad ready?
bool isLoading                  // Loading in progress?
bool isShowing                  // Currently displayed?

// Methods
Future<void> loadAd({...})     // Load rewarded ad
Future<bool> showAd({...})     // Show rewarded ad
void addStatusListener(cb)     // Listen for load status
void removeStatusListener(cb)  // Remove listener
void dispose()                  // Clean up

EasyBannerAd Widget

const EasyBannerAd({
  bool collapsible = false,  // Use collapsible format?
})

NativeAdManager

// Properties
bool isLoaded                   // Ad loaded?
bool isLoading                  // Loading in progress?
NativeAd? nativeAd             // The ad object

// Methods
Future<void> loadAd({...})     // Load native ad
void dispose()                  // Clean up

EasyNativeAd Widget

const EasyNativeAd({
  required String factoryId,   // Native ad factory ID
  required double height,      // Ad height
  double? width,               // Ad width (optional)
  Widget? loadingWidget,       // Loading placeholder
  Widget? errorWidget,         // Error placeholder
  bool hideOnLoading = true,   // Collapse while loading
  bool hideOnError = true,     // Collapse on error/no fill
  EdgeInsets padding,          // Padding around ad
  Color? backgroundColor,      // Background color
  BorderRadius? borderRadius,  // Corner radius
  VoidCallback? onAdLoaded,    // Callback when ad loads
  VoidCallback? onAdFailedToLoad, // Callback on load failure
})

Collapse Behavior (v1.3.6+): By default, EasyNativeAd collapses to zero height when loading or when an ad fails to load (e.g., no fill). This prevents empty white space in fixed-height layouts like bottomNavigationBar. Set hideOnLoading: false or hideOnError: false to show placeholder widgets instead.

Example with callbacks:

EasyNativeAd(
  factoryId: 'medium_template',
  height: 300,
  onAdLoaded: () => debugPrint('Native ad loaded!'),
  onAdFailedToLoad: () => debugPrint('Native ad failed to load'),
)

AdsEnabledManager

// Singleton instance
AdsEnabledManager.instance

// Properties
bool isEnabled                 // Ads enabled?
bool isDisabled                // Ads disabled?

// Methods
Future<void> disableAds()      // Disable all ads
Future<void> enableAds()       // Re-enable ads
void addListener(callback)     // Listen for changes
void removeListener(callback)  // Remove listener

// Stream
Stream<bool> stream            // Reactive state changes

🐛 Troubleshooting

Ads Not Loading

1. Check internet connection
2. Verify ad unit IDs are correct
3. Wait 24-48 hours after creating new ad units
4. Check logs for error codes:
   • Error 0: Internal error
   • Error 1: Invalid request
   • Error 2: Network error
   • Error 3: No fill

Consent Form Not Showing

1. Form only shows in GDPR regions (EU/UK/Switzerland)
2. Use VPN to test from GDPR region
3. Add test device ID for consent debugging

iOS Build Errors

1. Run pod install in ios folder
2. Update minimum iOS version to 13.0+
3. Ensure Info.plist has all required keys

Android Build Errors

1. Check minSdkVersion is 21+
2. Ensure AndroidManifest.xml has App ID
3. Run flutter clean && flutter pub get

📋 Checklist Before Release

• Use AdFlowConfig with your production ad unit IDs
• Remove testDeviceIds or leave empty
• Set enableConsentDebug: false
• Test on real devices
• Test consent flow in GDPR region (use VPN)
• Verify iOS ATT dialog appears
• Test all ad formats load and display
• Check ads don't block UI elements
• Review AdMob policies compliance
• Add privacy policy to app/store listing

📜 License

MIT License - Feel free to use in any project.

🙏 Credits

Built with:

• google_mobile_ads - Official Google Mobile Ads SDK
• Flutter - Google's UI toolkit

📞 Support

For issues or questions:

1. Check AdMob Help Center
2. Review google_mobile_ads documentation
3. See Flutter AdMob samples

Happy Monetizing! 💰