Native Google Ads #

A Flutter plugin for integrating Google Mobile Ads (AdMob) using native platform implementations. This plugin provides a simple and efficient way to display banner, native, interstitial, and rewarded ads in your Flutter applications.

Features #

✅ Native Implementation - Direct integration with Google Mobile Ads SDK
✅ iOS & Android Support - Full support for both platforms
✅ Banner Ads - Display banner ads in various sizes including adaptive
✅ Native Ads - Customizable ads that match your app's design
✅ Interstitial Ads - Full-screen ads at natural transition points
✅ Rewarded Ads - Reward users for watching video ads
✅ Platform Views - Native ad rendering using platform-specific views
✅ Flexible Configuration - Pass App IDs and configurations from Dart
✅ Test Mode - Easy switching between test and production ads
✅ Comprehensive Callbacks - Full lifecycle event handling
✅ Swift Package Manager - Modern iOS dependency management
✅ Kotlin Support - Modern Android implementation

Platform Support #

Platform	Minimum Version	Architecture
Android	API 24 (7.0)	Kotlin
iOS	13.0	Swift

Installation #

Add native_googleads to your pubspec.yaml:

dependencies:
  native_googleads: ^0.0.1

Then run:

flutter pub get

Platform Setup #

Android Setup #

1. Update `android/app/build.gradle`

Ensure your minimum SDK version is at least 24:

android {
    defaultConfig {
        minSdkVersion 24
        // ... other configurations
    }
}

2. Add AdMob App ID to AndroidManifest.xml

Add your AdMob App ID to android/app/src/main/AndroidManifest.xml:

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

Note: Use test App ID ca-app-pub-3940256099942544~3347511713 for development

iOS Setup #

1. Update iOS Deployment Target (or Swift Package Manager)

In your ios/Podfile, ensure the platform version is at least 13.0:

platform :ios, '13.0'

2. Add AdMob App ID to Info.plist

Add the following to your ios/Runner/Info.plist:

<key>GADApplicationIdentifier</key>
<string>ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy</string>

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

<!-- Required SKAdNetwork identifiers -->
<key>SKAdNetworkItems</key>
<array>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>cstr6suwn9.skadnetwork</string>
    </dict>
    <!-- Add other SKAdNetwork identifiers as needed -->
</array>

Note: Use test App ID ca-app-pub-3940256099942544~1458002511 for development

3. Update iOS Pods

cd ios
pod install

Usage #

Basic Usage #

import 'package:native_googleads/native_googleads.dart';

// Get the singleton instance
final ads = NativeGoogleads.instance;

// Initialize with App ID
await ads.initialize(appId: 'your-app-id');

// Or initialize with configuration
final config = AdConfig.production(
  appId: 'your-app-id',
  testDeviceIds: {'device-id-1', 'device-id-2'},
);
await ads.initializeWithConfig(config);

// Load and show banner ad
final bannerId = await ads.loadBannerAd(
  adUnitId: 'your-banner-ad-unit-id',
  size: BannerAdSize.adaptive,
);
if (bannerId != null) {
  await ads.showBannerAd(bannerId);
}

// Load and show native ad
final nativeAdId = await ads.loadNativeAd(
  adUnitId: 'your-native-ad-unit-id',
);
if (nativeAdId != null) {
  await ads.showNativeAd(nativeAdId);
}

// Preload and show interstitial ad
await ads.preloadInterstitialAd(
  adUnitId: 'your-interstitial-ad-unit-id',
);
await ads.showInterstitialAd(adUnitId: 'your-interstitial-ad-unit-id');

// Preload and show rewarded ad
await ads.preloadRewardedAd(
  adUnitId: 'your-rewarded-ad-unit-id',
);
await ads.showRewardedAd(adUnitId: 'your-rewarded-ad-unit-id');

Caching #

This plugin preloads and caches full-screen ads at the platform level per adUnitId.

Preload: call preloadInterstitialAd(adUnitId) or preloadRewardedAd(adUnitId) ahead of time.
Check: use isInterstitialReady(adUnitId) or isRewardedReady(adUnitId) before showing.
Show: call showInterstitialAd(adUnitId: ...) or showRewardedAd(adUnitId: ...).
Auto-preload: after an ad is dismissed or fails to show, the native layer auto-preloads the next ad for the same adUnitId to keep a warm cache.

Best practices:

Preload during app start or at natural pauses (e.g., level start).
Always check readiness for smoother UX; if not ready, delay or show alternative UI.
Use one adUnitId per placement; the cache holds one ready ad per type per adUnitId.

Preload → Check → Show (with auto-preload) #

import 'dart:io';
import 'package:native_googleads/native_googleads.dart';

final ads = NativeGoogleads.instance;
late final String interstitialId;

Future<void> initAds() async {
  await ads.initializeWithConfig(AdConfig.test());

  // Pick your placement’s ad unit ID
  interstitialId = Platform.isAndroid
      ? AdTestIds.androidInterstitial
      : AdTestIds.iosInterstitial;

  // 1) Preload early
  await ads.preloadInterstitialAd(adUnitId: interstitialId);

  // Optional: listen for lifecycle to reflect auto-preload
  ads.setAdCallbacks(
    onAdDismissed: (type) async {
      if (type == 'interstitial') {
        // Native side auto-preloads next; check readiness shortly after
        await Future.delayed(const Duration(milliseconds: 200));
        final ready = await ads.isInterstitialReady(interstitialId);
        // update UI state accordingly
      }
    },
  );
}

Future<void> maybeShowInterstitial() async {
  // 2) Check readiness before showing
  final ready = await ads.isInterstitialReady(interstitialId);
  if (!ready) {
    // Not ready: request preload again and bail or retry later
    await ads.preloadInterstitialAd(adUnitId: interstitialId);
    return;
  }

  // 3) Show when ready
  await ads.showInterstitialAd(adUnitId: interstitialId);
  // After dismiss, the native layer auto-preloads another ad for the same ID
}

Use the same pattern for rewarded ads with preloadRewardedAd, isRewardedReady, and showRewardedAd(adUnitId: ...).

Using Test Ads #

For development, always use test ad unit IDs:

import 'dart:io';

// Use test IDs during development
final testAdUnitId = Platform.isAndroid
    ? AdTestIds.androidInterstitial  // Test interstitial for Android
    : AdTestIds.iosInterstitial;      // Test interstitial for iOS

await ads.preloadInterstitialAd(adUnitId: testAdUnitId);

Available test IDs:

AdTestIds.androidInterstitial / AdTestIds.iosInterstitial
AdTestIds.androidRewarded / AdTestIds.iosRewarded
AdTestIds.androidBanner / AdTestIds.iosBanner
AdTestIds.androidNativeAdvanced / AdTestIds.iosNativeAdvanced

Setting Up Callbacks #

ads.setAdCallbacks(
  onAdDismissed: (adType) {
    print('Ad dismissed: $adType');
    // Handle ad dismissal
  },
  onAdShowed: (adType) {
    print('Ad showed: $adType');
    // Handle ad display
  },
  onAdFailedToShow: (adType, error) {
    print('Ad failed: $adType, error: $error');
    // Handle ad failure
  },
  onUserEarnedReward: (type, amount) {
    print('Reward earned: $amount $type');
    // Grant reward to user
  },
);

Working with Banner Ads #

Banner ads can be displayed in various sizes:

// Available banner sizes
BannerAdSize.banner           // 320x50
BannerAdSize.largeBanner       // 320x100
BannerAdSize.mediumRectangle   // 300x250
BannerAdSize.fullBanner        // 468x60
BannerAdSize.leaderboard       // 728x90
BannerAdSize.adaptive          // Adaptive size based on device width

// Load a banner ad
final bannerId = await ads.loadBannerAd(
  adUnitId: Platform.isAndroid 
    ? AdTestIds.androidBanner 
    : AdTestIds.iosBanner,
  size: BannerAdSize.adaptive,
);

// Show the banner
if (bannerId != null) {
  await ads.showBannerAd(bannerId);
}

// Hide the banner (keeps it loaded)
await ads.hideBannerAd(bannerId);

// Dispose when no longer needed
await ads.disposeBannerAd(bannerId);

You can also use the BannerAdWidget for easier integration:

BannerAdWidget(
  adUnitId: AdTestIds.androidBanner,
  size: BannerAdSize.adaptive,
  onAdLoaded: () => print('Banner loaded'),
  onAdFailedToLoad: (error) => print('Banner failed: $error'),
)

Working with Native Ads #

Native ads allow you to customize the ad appearance to match your app:

// Load a native ad
final nativeAdId = await ads.loadNativeAd(
  adUnitId: Platform.isAndroid 
    ? AdTestIds.androidNativeAdvanced 
    : AdTestIds.iosNativeAdvanced,
);

// Show the native ad
if (nativeAdId != null) {
  await ads.showNativeAd(nativeAdId);
}

// Dispose when no longer needed
await ads.disposeNativeAd(nativeAdId);

Use the NativeAdWidget for easier integration:

NativeAdWidget(
  adUnitId: AdTestIds.androidNativeAdvanced,
  height: 300,
  backgroundColor: Colors.white,
  onAdLoaded: () => print('Native ad loaded'),
  onAdFailedToLoad: (error) => print('Native ad failed: $error'),
)

Advanced Configuration #

// Create custom ad request configuration
final requestConfig = AdRequestConfig(
  keywords: ['games', 'sports'],
  contentUrl: 'https://example.com',
  nonPersonalizedAds: true,
);

// Preload ad with custom configuration
await ads.preloadInterstitialAd(
  adUnitId: 'your-ad-unit-id',
  requestConfig: requestConfig,
);

Complete Example #

import 'dart:io';
import 'package:flutter/material.dart';
import 'package:native_googleads/native_googleads.dart';

class AdExample extends StatefulWidget {
  @override
  _AdExampleState createState() => _AdExampleState();
}

class _AdExampleState extends State<AdExample> {
  final NativeGoogleads _ads = NativeGoogleads.instance;
  bool _interstitialReady = false;
  bool _rewardedReady = false;
  int _rewardAmount = 0;

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

  Future<void> _initializeAds() async {
    // Set up callbacks
    _ads.setAdCallbacks(
      onAdDismissed: (adType) {
        setState(() {
          if (adType == 'interstitial') _interstitialReady = false;
          if (adType == 'rewarded') _rewardedReady = false;
        });
      },
      onUserEarnedReward: (type, amount) {
        setState(() {
          _rewardAmount += amount;
        });
      },
    );

    // Initialize with test mode for development
    final config = AdConfig.test();
    await _ads.initializeWithConfig(config);
  }

  Future<void> _loadInterstitialAd() async {
    final adUnitId = Platform.isAndroid
        ? AdTestIds.androidInterstitial
        : AdTestIds.iosInterstitial;

    final success = await _ads.preloadInterstitialAd(adUnitId: adUnitId);
    setState(() => _interstitialReady = success);
  }

  Future<void> _showInterstitialAd() async {
    if (_interstitialReady) {
      await _ads.showInterstitialAd(adUnitId: Platform.isAndroid
          ? AdTestIds.androidInterstitial
          : AdTestIds.iosInterstitial);
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Native Google Ads Example')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text('Rewards: $_rewardAmount'),
            ElevatedButton(
              onPressed: _loadInterstitialAd,
              child: Text('Load Interstitial'),
            ),
            ElevatedButton(
              onPressed: _interstitialReady ? _showInterstitialAd : null,
              child: Text('Show Interstitial'),
            ),
          ],
        ),
      ),
    );
  }
}

API Reference #