preload_google_ads 1.0.7

preload_google_ads: ^1.0.7 copied to clipboard

🚀 Overview #

Preload Google Ads is a high-performance Flutter plugin designed to eliminate ad latency and provide a seamless, non-intrusive user experience. It background-preloads App Open, Interstitial, Rewarded, Rewarded Interstitial, Native (Small & Medium), and Banner (Anchored Adaptive & Collapsible) ads before they need to be displayed.

⚡ Key Features #

• 🏎️ Zero-Latency Ad Delivery: Background preloading queues ads before user navigation.
• 📱 All Major Formats: App Open, Interstitial, Rewarded, Rewarded Interstitial, Native, and Banner ads.
• 🎨 Adaptive & Collapsible Banners: Built-in anchored adaptive and collapsible banner support.
• 🌙 Light & Dark Mode: Dynamic native ad style sync with system/app theme.
• 📊 Match-Rate Optimization (>95%): Intelligent click counter gating and 4-hour TTL caching.
• 🛠️ Diagnostic Ad Counter: Live visual stats widget tracking loads and impressions.

Preview #

Below are some previews showing ad preloading in action. Notice the instant display!

Getting Started #

1. Installation #

Add this to your pubspec.yaml:

dependencies:
  preload_google_ads: ^1.0.7

Or run:

flutter pub add preload_google_ads

2. Platform Setup #

Important: Configure your AdMob App ID in both Android and iOS projects to avoid crashes.

Android

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

<manifest>
    <application>
        <meta-data
            android:name="com.google.android.gms.ads.APPLICATION_ID"
            android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"/>
    </application>
</manifest>

iOS

Update ios/Runner/Info.plist:

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

Basic Usage #

Initialize the plugin in your main() function. This kicks off the background preloading immediately.

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

  // Initialize and start preloading
  await PreloadGoogleAds.instance.initialize(
    adConfigData: AdConfigData(
      adIDs: AdIDS(
        appOpenId: AdTestIds.appOpen,
        bannerId: AdTestIds.banner,
        nativeId: AdTestIds.native,
        interstitialId: AdTestIds.interstitial,
        rewardedId: AdTestIds.rewarded,
        rewardedInterstitialId: AdTestIds.rewardedInterstitial,
      ),
    ),
  );

  runApp(const MyApp());
}

Advanced Configuration #

Click Counters & AD Flags #

Control specifically which ads to show and how frequently they appear.

PreloadGoogleAds.instance.initialize(
  adConfigData: AdConfigData(
    adCounter: AdCounter(
      interstitialCounter: 2,        // Show every 2 clicks
      nativeCounter: 0,              // Show every time
      rewardedCounter: 1,            // Show every click
      rewardedInterCounter: 1,       // Show every click
    ),
    adFlag: AdFlag(
      showAd: true,
      showBanner: true,
      showInterstitial: true,
      showNative: true,
      showOpenApp: true,
      showRewarded: true,
      showRewardedInter: true,
      showSplashAd: false,
    ),
  ),
);

Native Ad Custom Styling #

Customize the appearance of native ads with light and dark mode tokens.

NativeADLayout(
  padding: const EdgeInsets.all(8),
  lightDecoration: BoxDecoration(
    color: Colors.white,
    border: Border.all(color: Colors.grey.shade300),
    borderRadius: BorderRadius.circular(12),
  ),
  darkDecoration: BoxDecoration(
    color: const Color(0xFF1E293B),
    border: Border.all(color: const Color(0xFF334155)),
    borderRadius: BorderRadius.circular(12),
  ),
  lightCustomNativeADStyle: CustomNativeADStyle(
    titleColor: Colors.black,
    bodyColor: Colors.grey.shade700,
    buttonBackground: Colors.blueAccent,
    buttonForeground: Colors.white,
    buttonRadius: 10,
    tagBackground: Colors.amber,
    tagForeground: Colors.black,
  ),
  darkCustomNativeADStyle: CustomNativeADStyle.dark(
    titleColor: Colors.white,
    bodyColor: Colors.grey.shade300,
    buttonBackground: Colors.indigoAccent,
    buttonForeground: Colors.white,
    buttonRadius: 10,
  ),
)

Showing Ads #

Code Examples for All Ad Formats #

1. Native Ad (Medium / Small)

// Native Medium Ad
PreloadGoogleAds.instance.showNativeAd(
  key: const ValueKey('home_native_ad'),
  nativeADType: NativeADType.medium,
);

// Native Small Ad
PreloadGoogleAds.instance.showNativeAd(
  key: const ValueKey('feed_native_ad'),
  nativeADType: NativeADType.small,
);

2. Standard Anchored Banner Ad

PreloadGoogleAds.instance.showBannerAd();

3. Collapsible Banner Ad (Bottom / Top)

// Bottom Collapsible Banner
PreloadGoogleAds.instance.showCollapsibleBannerAd(
  collapsiblePosition: CollapsibleBannerPosition.bottom,
);

// Top Collapsible Banner
PreloadGoogleAds.instance.showCollapsibleBannerAd(
  collapsiblePosition: CollapsibleBannerPosition.top,
);

4. Interstitial Ad

PreloadGoogleAds.instance.showInterstitialAd(
  callBack: (ad, error) {
    if (error != null) {
      print("Interstitial failed to show: ${error.message}");
    }
    // Perform navigation or action after ad is closed
  },
);

5. Rewarded Ad

PreloadGoogleAds.instance.showRewardedAd(
  callBack: (ad, error) {
    if (error != null) {
      print("Rewarded ad failed to show: ${error.message}");
    }
  },
  onReward: (ad, rewardItem) {
    print("User earned reward: ${rewardItem.amount} ${rewardItem.type}");
  },
);

6. Rewarded Interstitial Ad

PreloadGoogleAds.instance.showRewardedInterstitialAd(
  callBack: (ad, error) {
    if (error != null) {
      print("Rewarded Interstitial failed to show: ${error.message}");
    }
  },
  onReward: (ad, rewardItem) {
    print("User earned rewarded interstitial reward!");
  },
);

7. App Open Ad

PreloadGoogleAds.instance.showOpenApp();

Quick Reference Table #

Splash Ad Callback #

Show an app open ad immediately on splash and navigate when ready.

PreloadGoogleAds.instance.setSplashAdCallback((ad, error) {
  // Navigate to Home after splash ad completes
  Navigator.pushReplacement(context, MaterialPageRoute(builder: (_) => const HomeView()));
});

Diagnostic Counter #

Enable the built-in counter to track ad status in real-time during development.

PreloadGoogleAds.instance.showAdCounter(showCounter: true);

Support & Contributions #

We welcome contributions!

• Bugs: Open an issue on GitHub.
• Feature Request: Open a discussion.
• Starred: If this package helps you, give it a ⭐ on pub.flutter-io.cn.

License & Contact #

• License: MIT License
• Author: CoddyNet Infotech
• Email: coddynet@gmail.com
• GitHub: https://github.com/coddyNet

Built with passion for Flutter Developers seeking top-tier performance.