google_admob_sdk 0.0.2

A Flutter plugin for Google Mobile Ads (AdMob) with centralized Ad Unit ID management, load duration metrics, adKey tracking, and pre-built ad widgets & managers.

Google AdMob SDK for Flutter (google_admob_sdk)

A comprehensive, production-ready Flutter SDK wrapper for Google Mobile Ads (google_mobile_ads) with built-in Ad Unit ID management per platform, load time performance tracking, Firebase Analytics integration, customizable ProgressIndicators, and pre-built ad widgets & managers.

---

Features

• ⚡ Easy Initialization: Initialize Google Mobile Ads with custom or test configuration in a single line.
• 🎯 Ad ID Management: Centralized AdIdConfig for Android & iOS supporting 6 ad types (Banner, Interstitial, Rewarded, Rewarded Interstitial, App Open, Native) with fallback to Google official test IDs.
• 📊 Performance & Event Analytics: Built-in AdAnalyticsLogger supporting FirebaseAdLogger, ConsoleAdLogger, or custom loggers to track ad load duration (ms), impressions, clicks, and load failures with adKey tracking (key_<ad_type>).
• 🖼️ Banner Ad Widget: BannerAdWidget widget with automatic state management, customizable progressIndicator, loadingBuilder, and errorBuilder.
• 🎬 Interstitial Ad Manager: InterstitialAdManager with preloading, auto-reload on dismiss/fail, and lifecycle management.
• 🎁 Rewarded Ad Manager: RewardedAdManager for incentivized video ads with reward callbacks.
• 🏆 Rewarded Interstitial Ad Manager: RewardedInterstitialAdManager for interstitial rewarded ads.
• 🚪 App Open Ad Manager: AppOpenAdManager with built-in ad expiration check (4 hours max age per Google guidelines).
• 🎨 Native Ad Widget: NativeAdWidget with customizable template styles, progressIndicator, loadingBuilder, and errorBuilder.

---

Getting Started

1. Add Dependency

Add google_admob_sdk to your pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  google_admob_sdk:
    path: ../google_admob_sdk # Or git / pub package path

2. Platform Configuration

Android Setup (AndroidManifest.xml)

Add your AdMob App ID inside the <application> tag:

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

iOS Setup (Info.plist)

Add GADApplicationIdentifier to ios/Runner/Info.plist:

<key>GADApplicationIdentifier</key>
<string>ca-app-pub-3940256099942544~1458002511</string> <!-- Test App ID -->
<key>SKAdNetworkItems</key>
<array>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>cstr6suwn9.skadnetwork</string>
    </dict>
</array>

---

Usage

1. SDK Initialization

Initialize GoogleAdmobSdk in your main() function:

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

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

  await GoogleAdmobSdk.initialize(
    config: AdIdConfig(
      android: const PlatformAdIds(
        bannerId: 'ca-app-pub-xxx/android_banner',
        interstitialId: 'ca-app-pub-xxx/android_interstitial',
        rewardedId: 'ca-app-pub-xxx/android_rewarded',
        rewardedInterstitialId: 'ca-app-pub-xxx/android_rewarded_interstitial',
        appOpenId: 'ca-app-pub-xxx/android_app_open',
        nativeId: 'ca-app-pub-xxx/android_native',
      ),
      ios: const PlatformAdIds(
        bannerId: 'ca-app-pub-xxx/ios_banner',
        interstitialId: 'ca-app-pub-xxx/ios_interstitial',
        rewardedId: 'ca-app-pub-xxx/ios_rewarded',
        rewardedInterstitialId: 'ca-app-pub-xxx/ios_rewarded_interstitial',
        appOpenId: 'ca-app-pub-xxx/ios_app_open',
        nativeId: 'ca-app-pub-xxx/ios_native',
      ),
    ),
    logger: FirebaseAdLogger(), // Log performance metrics to Firebase Analytics
    enableConsoleLog: true,     // Print ad load duration and events in debug console
  );

  runApp(const MyApp());
}

---

2. Banner Ad Widget (Custom progressIndicator)

Embed BannerAdWidget directly into your widget tree and pass any custom progressIndicator:

BannerAdWidget(
  adKey: 'home_bottom_banner',
  adSize: AdSize.banner,
  // Custom ProgressIndicator widget
  progressIndicator: CircularProgressIndicator(
    color: Colors.blueAccent,
    strokeWidth: 3.0,
  ),
  onAdLoaded: (ad) => print('Banner Loaded'),
  onAdFailedToLoad: (error) => print('Banner Failed: $error'),
)

---

3. Native Ad Widget (Custom progressIndicator)

Embed NativeAdWidget with custom progressIndicator and nativeTemplateStyle:

NativeAdWidget(
  adKey: 'feed_native_ad',
  height: 300,
  progressIndicator: const LinearProgressIndicator(),
  nativeTemplateStyle: NativeTemplateStyle(
    templateType: TemplateType.medium,
  ),
)

---

4. Interstitial Ad

Use InterstitialAdManager to load and present interstitial ads:

final interstitialManager = InterstitialAdManager();

// Preload Interstitial Ad with a custom placement key
interstitialManager.loadAd(adKey: 'level_complete_interstitial');

// Show ad when ready
if (interstitialManager.isAdLoaded) {
  interstitialManager.showAd(
    onAdDismissedFullScreenContent: () => print('Closed'),
  );
}

---

5. Rewarded Ad & Rewarded Interstitial Ad

Use RewardedAdManager or RewardedInterstitialAdManager:

final rewardedManager = RewardedAdManager();

rewardedManager.loadAd(adKey: 'extra_lives_rewarded');

if (rewardedManager.isAdLoaded) {
  rewardedManager.showAd(
    onUserEarnedReward: (ad, reward) {
      print('User earned: ${reward.amount} ${reward.type}');
    },
  );
}

---

6. App Open Ad

Use AppOpenAdManager for app startup or resume ads:

final appOpenManager = AppOpenAdManager();

await appOpenManager.loadAd(adKey: 'app_launch_open_ad');

if (appOpenManager.isAdAvailable) {
  await appOpenManager.showAdIfAvailable();
}

---

Analytics & Performance Logging (adKey & key_<ad_type>)

google_admob_sdk automatically measures ad loading times and logs events:

• ad_load_performance: Duration in milliseconds (load_duration_ms), success status, error codes.
• ad_impression_logged: Fired on ad impressions.
• ad_click_logged: Fired on user ad clicks.

When you pass an adKey parameter (e.g. 'home_bottom_banner'), the SDK automatically passes both ad_key and dynamic key_<ad_type> parameters to Firebase Analytics:

Parameter Name in Analytics	Value Example	Description
ad_key	'home_bottom_banner'	Generic ad placement key
key_banner	'home_bottom_banner'	Type-specific key for Banner ads
key_interstitial	'level_complete_interstitial'	Type-specific key for Interstitial ads
key_rewarded	'extra_lives_rewarded'	Type-specific key for Rewarded ads
key_rewardedInterstitial	'bonus_stage_rewarded_interstitial'	Type-specific key for Rewarded Interstitial ads
key_appOpen	'app_launch_open_ad'	Type-specific key for App Open ads
key_native	'feed_native_ad'	Type-specific key for Native ads