capacitor-admob-nextgen

v1.0.8

Published

a month ago

Google Mobile Ads Next Gen SDK for Capacitor. High performance and modular architecture.

Downloads

701

0High
0Medium
0Low

emi-indo

capacitor capacitor-admob capacitor-admob-nextgen plugin native admob ads monetization google-mobile-ads next-gen

capacitor-admob-nextgen

The Ultimate AdMob Monetization Solution for Capacitor.

This plugin integrates the newly announced Google Mobile Ads (GMA) Next-Gen SDK into Capacitor. It is designed with a high-performance, modular architecture and zero mandatory native configuration.

Check all plugin release notes:

📦 Current SDK Versions (Maintained & Up-to-Date)

This plugin is regularly updated to support the latest standards.

| Component | Platform | Version | Release Notes | | :--- | :--- | :--- | :--- | | GMA Next-Gen SDK | Android | 1.2.1 | View Notes | | UMP SDK | Android | 4.0.0 | View Notes | | Mobile Ads SDK | iOS | 13.3.0 | View Notes | | UMP SDK | iOS | 3.1.0 | View Notes |

✨ Key Features

🚀 Core & Performance

Next-Gen Preloading API: Introduces continuous background ad buffering. Pull ads instantly with zero latency.
Classic Single-Load API: Fully supports traditional ad loading methods for backwards compatibility.
Smart Caching & Rate Limiting: Built-in anti-spam protections to safeguard AdMob accounts from Invalid Traffic penalties.
Automated Native Setup: Effortlessly inject App IDs into AndroidManifest.xml and Info.plist using Capacitor CLI Hooks.
Integrated UMP: Full support for Google's User Messaging Platform for GDPR and App Tracking Transparency (ATT) compliance.

🧩 Banner Ads

IMPORTANT: The Smart WebView Push and Adaptive Layout handling is exclusively designed, thoroughly tested, and handled specifically for Capacitor 8+ (API 36).
Using this plugin on Capacitor 7+ (API 35) or below may not yield expected results, as the layout engine is strictly tailored for the Capacitor 8 architecture.

Example video
Smart WebView Push: Dynamically adjusts WebView margins when Banner Ads are displayed to prevent UI overlap.
Isolated OS Branching: Uses distinct native logic for Android 15+ (Edge-to-Edge) and Android 14 or below to guarantee layout stability.
Immersive Fullscreen Support: Automatically detects and adapts perfectly whether the app is in normal or immersive fullscreen mode.

📱 Full-Screen Ads (Interstitial, Rewarded, App Open)

Safe Area Workaround: Includes an automated background lifecycle fix to prevent full-screen ad close buttons ("X") from being hidden under system bars on Android 15+.

⚠️ Important Notices

1. Built from Scratch with Battle-Tested Logic

This is not a fork of any existing Capacitor plugin. It is built entirely from scratch using the official @capacitor/plugin generator.
While the Capacitor wrapper is new, the core engine inherits years of proven optimizations from the author's highly successful Cordova implementations (cordova-plugin-admob-nextgen and emi-indo-cordova-plugin-admob).
Focus on eCPM & Account Health: This plugin is strictly engineered to maintain a healthy balance between ad requests and actual impressions. Generating thousands of unshown ad requests severely damages Click-Through Rates (CTR) and eCPM. This architecture ensures high-efficiency ad delivery to protect AdMob account health and maximize monetization metrics.

2. Next-Gen SDK ONLY

This plugin specifically targets the newly announced GMA Next-Gen SDK, which is vastly different from the legacy SDK.

Learn about the architectural differences here: Announcing Google Mobile Ads Next-Gen.
CRITICAL: Do NOT combine the legacy Google Mobile Ads SDK and the Next-Gen SDK in the same project. It will cause your application to crash during the build process.
If you still need the legacy SDK, please use the standard @capacitor-community/admob plugin.

📦 Installation

npm install capacitor-admob-nextgen
npx cap sync

⚙️ Configuration (App ID Setup)

Google's UMP SDK strictly requires your AdMob App ID to be present in your native AndroidManifest.xml (Android) and Info.plist (iOS) before initialization. This plugin offers two ways to handle this:

Option A: Automatic Setup (Highly Recommended)

Avoid manual XML editing. This plugin provides a Capacitor CLI Hook to automatically inject your App IDs every time you run npx cap sync.

Add your AdMob configuration to your app's root package.json:

{
  "name": "your-app-name",
  "admob": {
    "androidAppId": "ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy",
    "iosAppId": "ca-app-pub-xxxxxxxxxxxxxxxx~zzzzzzzzzz",
    "userTrackingDescription": "This identifier will be used to deliver personalized ads to you." 
  }
}

{
  "scripts": {
    "capacitor:sync:after": "node node_modules/capacitor-admob-nextgen/scripts/admob-manifest.js"
  }
}

Transparency Note: This plugin does NOT secretly manipulate your project. The injection script is strictly OPT-IN and only runs if you explicitly declare the hook above.

Option B: Manual Setup

If you prefer total manual control, simply do not add the script to your package.json.

For Android: Open android/app/src/main/AndroidManifest.xml and add the following inside the <application> tag:

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

For iOS: Open ios/App/App/Info.plist and add:

<key>GADApplicationIdentifier</key>
<string>ca-app-pub-xxxxxxxxxxxxxxxx~zzzzzzzzzz</string>
<key>NSUserTrackingUsageDescription</key>
<string>This identifier will be used to deliver personalized ads to you.</string>

🧩 Native Ads Setup (Opt-In Feature)

Official Google Templates: Plugin this utilize the official AdMob Native Templates provided by Google, ensuring your ads meet the highest professional and production standards.
- Android Template Source
- iOS Template Source

Unlike standard Banner or Interstitial ads, Native Ads require specific UI template files (.xml for Android, .xib for iOS) and additional layout dependencies (such as Android's ConstraintLayout).

To maintain a clean architecture, keep the plugin extremely lightweight, and prevent potential XML resource conflicts with other plugins in your project, Native Ads are strictly OPT-IN. The necessary templates and dependencies are dynamically injected via a Capacitor hook only if you explicitly enable them.

To enable Native Ads, update your app's root package.json:

Add "enableNativeAds" inside your "admob" configuration. You can enable it globally by setting it to true, or target specific platforms using an object (e.g., { "ios": true, "android": false }).
Chain the admob-native.js script to your existing capacitor:sync:after (or before) hook.

{
  "name": "your-app-name",
  "admob": {
    "androidAppId": "ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy",
    "iosAppId": "ca-app-pub-xxxxxxxxxxxxxxxx~zzzzzzzzzz",
    "enableNativeAds": { "ios": true, "android": true }
  },
  "scripts": {
    "capacitor:sync:after": "node node_modules/capacitor-admob-nextgen/scripts/admob-manifest.js && node node_modules/capacitor-admob-nextgen/scripts/admob-native.js"
  }
}

💡 Transparency Note: If you do not need Native Ads on a specific platform, simply set it to false (e.g., { "ios": true, "android": false }). If you don't need Native Ads at all, set "enableNativeAds": false (or omit it entirely). The dynamic hook ensures that any disabled platform will completely exclude the Native Ad UI templates and ConstraintLayout dependency during your native app compilation.

🤝 Third-Party Mediation (Opt-In Feature)

📖 Step-by-Step AdMob UI Setup

Integrating third-party ad networks (like Facebook/Meta, AppLovin, Unity, etc.) traditionally bloats your app size and introduces dependency conflicts.

To keep this plugin strictly lightweight, Mediation is completely OPT-IN. Plugin this built a Next-Gen dynamic injector that perfectly bridges Android's build.gradle and iOS's Package.swift (SPM) or Podfile (CocoaPods). The plugin supports 16 major ad networks, and they will only be installed if you explicitly configure them.

To enable Mediation, update your app's root package.json:

Add the "admobMediation" configuration block.
Control exact platform behaviors using the "platforms" toggle (perfect for Capacitor 8+ SPM support).
Chain the admob-mediation.js script to your existing hook.

{
  "name": "your-app-name",
  "admob": {
    "androidAppId": "ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy",
    "iosAppId": "ca-app-pub-xxxxxxxxxxxxxxxx~zzzzzzzzzz"
  },
  "admobMediation": {
    "platforms": { "ios": true, "pod": false, "spm": true, "android": true },
    "enableFacebook": true,
    "enableAppLovin": true,
    "enableUnity": false,
    "enableVungle": false,
    "keyAppLovin": "YOUR_APPLOVIN_SDK_KEY_HERE"
  },
  "scripts": {
    "capacitor:sync:after": "node node_modules/capacitor-admob-nextgen/scripts/admob-manifest.js && node node_modules/capacitor-admob-nextgen/scripts/admob-mediation.js"
  }
}

💡 Transparency Note (Clean Sweep Architecture): If you disable a network (e.g., "enableUnity": false), the dynamic hook acts as a garbage collector. It will strictly perform a "clean sweep" using Regex, entirely ripping out that specific SDK from your build.gradle, .podspec, and Package.swift files during npx cap sync. Your project will never suffer from abandoned code leftovers.

🍎 Note: iOS (Capacitor 8+ & SPM)

Capacitor 8+ Recommendation: Swift Package Manager (SPM). This plugin natively supports injecting Mediation dependencies directly into your Package.swift file (by setting "spm": true in your mediation config).

If a dependency is missing, open the project in Xcode 26+.
Click File at the top menu, and select Packages > Reset Package Caches. This will forcefully download all dependencies registered in your Package.swift.

Legacy Support (CocoaPods): Because the AdTech industry is still transitioning, some older third-party adapters might not fully support SPM yet. CocoaPods remains available as a fallback. If you need to use CocoaPods (by setting "pod": true and "spm": false), you must recreate your iOS folder:

Remove your existing SPM-based iOS folder:
```
rm -rf ios
```
Re-add the iOS platform using the CocoaPods flag:
```
npx cap add ios --packagemanager CocoaPods
```
Run npx cap sync.

Note: IOS

Capacitor 8 Recommendation: Swift Package Manager (SPM). When a dependency is missing, open the project in Xcode 26+

click File at the top, and select Package > Reset Package Caches. This will download all dependencies in Package.swift.
Because CocoaPods remains available as an alternative.

Remove your existing SPM-based iOS folder:
```
rm -rf ios
```
Re-add the iOS platform using the CocoaPods flag:

   npx cap add ios --packagemanager CocoaPods

Run npx cap sync

🚀 Example Usage

Check out the comprehensive, interactive dashboard example to see how to implement UMP, classic loading, and the new Preloading API: 👉 capacitor-welcome.js Example Project

  <style>
          :host {
            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
            display: block;
            width: 100vw;
            min-height: 100vh; /* Let it grow down */
            margin: 0;
            padding: 0;
            background-color: #000; 
          }

          .app-container {
            display: flex;
            flex-direction: column;
            min-height: 100vh;
            background-color: #f4f5f8;
            padding-top: env(safe-area-inset-top, 0px);
            padding-bottom: env(safe-area-inset-bottom, 0px);
            box-sizing: border-box;
          }

          .debug-header, .debug-footer {
            background: repeating-linear-gradient(45deg, #ffc409, #ffc409 10px, #e0ab08 10px, #e0ab08 20px);
            color: #000; text-align: center; font-weight: 900; font-size: 12px; padding: 8px 0;
            text-transform: uppercase; letter-spacing: 2px; flex-shrink: 0; z-index: 10;
          }

          .debug-header { position: sticky; top: 0; }
          .debug-footer { position: sticky; bottom: 0; }

          .scroll-area {
            padding: 10px;
            display: grid;
            grid-template-columns: 1fr 1fr; 
            gap: 10px;
            align-content: start;
          }

          .section {
            background: white; border-radius: 8px; padding: 10px;
            box-shadow: 0 1px 3px rgba(0,0,0,0.1);
            display: flex; flex-direction: column; gap: 6px;
          }
          .section.full-width { grid-column: 1 / -1; }
          .section-title { font-size: 13px; font-weight: bold; color: #3880ff; text-align: center; margin: 0 0 4px 0; }
          
          .controls {
            background: #f8f9fa; border: 1px solid #e0e0e0; border-radius: 6px; padding: 6px;
            display: grid; grid-template-columns: 1fr 1fr; gap: 4px; font-size: 11px; align-items: center;
          }
          .controls label { display: flex; justify-content: space-between; align-items: center; }
          .controls select, .controls input { padding: 2px; margin: 0; }

          .btn-row { display: flex; gap: 6px; }
          .btn {
            flex: 1; border: none; border-radius: 4px; padding: 8px 4px;
            font-size: 11px; font-weight: bold; color: white; cursor: pointer; text-align: center;
            transition: all 0.2s ease;
          }
          .btn:active { opacity: 0.8; transform: scale(0.98); }
          
          .btn-sys { background-color: #3880ff; } 
          .btn-load { background-color: #eb445a; } 
          .btn-show { background-color: #2dd36f; } 
          .btn-preload { background-color: #8e24aa; } 
          .btn-alt { background-color: #92949c; } 
          
          .btn:disabled { 
            background-color: #cccccc !important; 
            color: #888888 !important;
            cursor: not-allowed; 
            transform: none;
            opacity: 0.7;
          }

          .terminal-wrapper {
            height: 32vh; 
            background-color: #222428;
            display: flex; flex-direction: column;
            border-top: 2px solid #111;
          }
          .terminal-header {
            background: #1a1b1e; color: #fff; font-size: 10px; padding: 4px 10px; font-weight: bold;
            display: flex; justify-content: space-between;
          }
          .status-badge { color: #eb445a; }
          .status-badge.ready { color: #2dd36f; }

          #terminal {
            flex: 1; overflow-y: auto; padding: 8px 10px;
            color: #2fdf75; font-family: monospace; font-size: 11px; word-wrap: break-word;
          }
          .log-time { color: #888; font-size: 9px; margin-right: 4px; }

          .native-ad-placeholder {
            width: 100%;
            height: 150px; 
            border: 2px dashed #92949c;
            border-radius: 8px;
            margin-top: 10px;
            display: flex;
            align-items: center;
            justify-content: center;
            color: #92949c;
            font-size: 12px;
            font-weight: bold;
            text-align: center;
            background-color: rgba(146, 148, 156, 0.1);
          }
         </style>

Install

To use npm:

npm install capacitor-admob-nextgen

To use yarn:

yarn add capacitor-admob-nextgen

Sync native files:

npx cap sync

API

AdMob Next-Gen Plugin

CRITICAL: Proper Execution Order

To comply with Google's policies (GDPR, COPPA, etc.), you MUST follow this exact execution order when your app starts:

Request Consent (UMP): await AdMobNextGen.requestConsentInfo(...) Always do this first. It checks if the user needs to see a privacy form.
Initialize SDK: await AdMobNextGen.initialize(...) Do this REGARDLESS of whether the consent form was shown or not. The SDK needs to boot up using the consent status gathered in step 1.
Load Ads: e.g., await AdMobNextGen.loadInterstitial(...)
Show Ads: e.g., await AdMobNextGen.showInterstitial()

requestTrackingAuthorization()

requestTrackingAuthorization() => Promise<TrackingAuthorizationResult>

Requests App Tracking Transparency (ATT) authorization from the user. This is explicitly required for iOS 14.5+ to display personalized ads. On Android and Web, it automatically returns { status: 'authorized' }.

@returns A promise resolving to the authorization status.

Returns: Promise<TrackingAuthorizationResult>

requestConsentInfo(...)

requestConsentInfo(options?: ConsentOptions | undefined) => Promise<ConsentStatusResult>

Requests consent information update and shows the consent form if required (UMP SDK). MUST be called before initialize().

| Param | Type | | ------------- | --------------------------------------------------------- | | options | ConsentOptions |

Returns: Promise<ConsentStatusResult>

showPrivacyOptionsForm()

showPrivacyOptionsForm() => Promise<ConsentStatusResult>

Shows the privacy options form if the user wants to change their consent later. Usually triggered by a button in your app's Settings menu.

Returns: Promise<ConsentStatusResult>

getTCData()

getTCData() => Promise<TCDataResult>

Reads the IAB TCF v2.2 strings directly from SharedPreferences. Useful if you need to pass consent strings to a custom analytics server.

Returns: Promise<TCDataResult>

initialize(...)

initialize(options: InitializeOptions) => Promise<InitializeResult>

Initializes the GMA Next-Gen SDK. MUST be called after requestConsentInfo().

| Param | Type | | ------------- | --------------------------------------------------------------- | | options | InitializeOptions |

Returns: Promise<InitializeResult>

loadAppOpen(...)

loadAppOpen(options: AppOpenOptions) => Promise<void>

Loads an App Open Ad.

| Param | Type | | ------------- | --------------------------------------------------------- | | options | AppOpenOptions |

showAppOpen()

showAppOpen() => Promise<void>

Shows the loaded App Open Ad.

createBanner(...)

createBanner(options: BannerOptions) => Promise<void>

Creates and loads a Banner Ad. It can automatically show upon loading if isAutoShow is true.

| Param | Type | | ------------- | ------------------------------------------------------- | | options | BannerOptions |

showBanner()

showBanner() => Promise<void>

Shows a previously created (and potentially hidden) banner ad.

hideBanner()

hideBanner() => Promise<void>

Temporarily hides the banner ad without destroying it.

destroyBanner()

destroyBanner() => Promise<void>

Destroys the banner ad and cleans up resources from the view hierarchy.

loadInterstitial(...)

loadInterstitial(options: InterstitialOptions) => Promise<void>

Loads an Interstitial Ad.

| Param | Type | | ------------- | ------------------------------------------------------------------- | | options | InterstitialOptions |

showInterstitial()

showInterstitial() => Promise<void>

Shows the loaded Interstitial Ad.

loadRewarded(...)

loadRewarded(options: RewardedOptions) => Promise<void>

Loads a Rewarded Ad.

| Param | Type | | ------------- | ----------------------------------------------------------- | | options | RewardedOptions |

showRewarded()

showRewarded() => Promise<void>

Shows the loaded Rewarded Ad.

loadRewardedInterstitial(...)

loadRewardedInterstitial(options: RewardedInterstitialOptions) => Promise<void>

Loads a Rewarded Interstitial Ad.

| Param | Type | | ------------- | ----------------------------------------------------------------------------------- | | options | RewardedInterstitialOptions |

showRewardedInterstitial()

showRewardedInterstitial() => Promise<void>

Shows the loaded Rewarded Interstitial Ad.

showNativeAd(...)

showNativeAd(options: NativeAdOptions) => Promise<{ width: number; height: number; }>

Loads and displays a Native Ad at the specified screen coordinates using predefined templates.

💡 NOTE: To use this, you must set "enableNativeAds": true in your app's package.json under the "admob" configuration, and run npx cap sync.
@param options The configuration and layout parameters for the Native Ad.

| Param | Type | | ------------- | ----------------------------------------------------------- | | options | NativeAdOptions |

Returns: Promise<{ width: number; height: number; }>

hideNativeAd()

hideNativeAd() => Promise<void>

Hides and destroys the currently displayed Native Ad.

startPreloadAppOpen(...)

startPreloadAppOpen(options: AppOpenOptions) => Promise<void>

⚠️ CRITICAL NOTE: Do NOT mix the Classic API with the Next-Gen API. If you use startPreload..., you must ONLY use pollAndShow... to display the ad. Calling classic methods like load() or show() while a preloader is active will cause unexpected behavior.

Starts the background preloader buffer for App Open Ads. This tells the SDK to automatically fetch and cache ads continuously.
⚠️ Do not use loadAppOpen() if you are using this preloader method.

🍎 iOS LIMITATION: The Next-Gen Preloading API is currently an Android-exclusive feature within the GMA SDK. When building or running on iOS devices, you MUST use the Classic single-load API (e.g., loadAppOpen() and showAppOpen()). Calling Preload methods on iOS will not trigger the native preloader.

| Param | Type | | ------------- | --------------------------------------------------------- | | options | AppOpenOptions |

pollAndShowAppOpen()

pollAndShowAppOpen() => Promise<void>

Pulls the next available ad from the preload buffer and shows it instantly. If the buffer is empty (exhausted), this will throw an error.

isAppOpenPreloadAvailable(...)

isAppOpenPreloadAvailable(options?: { adUnitId?: string | undefined; } | undefined) => Promise<{ isAvailable: boolean; }>

Synchronously checks if an ad is currently ready in the preload buffer.

| Param | Type | | ------------- | ----------------------------------- | | options | { adUnitId?: string; } |

Returns: Promise<{ isAvailable: boolean; }>

startPreloadBanner(...)

startPreloadBanner(options: BannerOptions & { bufferSize?: number; }) => Promise<void>

Starts the background preloader buffer for Banner Ads.

| Param | Type | | ------------- | ---------------------------------------------------------------------------------- | | options | BannerOptions & { bufferSize?: number; } |

pollAndShowBanner()

pollAndShowBanner() => Promise<void>

Pulls the next available Banner ad from the preload buffer and renders it immediately.

hidePreloadedBanner()

hidePreloadedBanner() => Promise<void>

Hides the preloaded banner without destroying it.

destroyPreloadedBanner()

destroyPreloadedBanner() => Promise<void>

Destroys the current preloaded banner view.

isBannerPreloadAvailable(...)

isBannerPreloadAvailable(options?: { adUnitId?: string | undefined; } | undefined) => Promise<{ isAvailable: boolean; }>

Synchronously checks if a Banner ad is ready in the preload buffer.

| Param | Type | | ------------- | ----------------------------------- | | options | { adUnitId?: string; } |

Returns: Promise<{ isAvailable: boolean; }>

startPreloadInterstitial(...)

startPreloadInterstitial(options: InterstitialOptions & { bufferSize?: number; }) => Promise<void>

Starts the background preloader buffer for Interstitial Ads.

| Param | Type | | ------------- | ---------------------------------------------------------------------------------------------- | | options | InterstitialOptions & { bufferSize?: number; } |

pollAndShowInterstitial()

pollAndShowInterstitial() => Promise<void>

Pulls the next available Interstitial ad from the preload buffer and shows it instantly.

isInterstitialPreloadAvailable(...)

isInterstitialPreloadAvailable(options?: { adUnitId?: string | undefined; } | undefined) => Promise<{ isAvailable: boolean; }>

Synchronously checks if an Interstitial ad is ready in the preload buffer.

| Param | Type | | ------------- | ----------------------------------- | | options | { adUnitId?: string; } |

Returns: Promise<{ isAvailable: boolean; }>

startPreloadRewarded(...)

startPreloadRewarded(options: RewardedOptions & { bufferSize?: number; }) => Promise<void>

Starts the background preloader buffer for Rewarded Ads.

| Param | Type | | ------------- | -------------------------------------------------------------------------------------- | | options | RewardedOptions & { bufferSize?: number; } |

pollAndShowRewarded()

pollAndShowRewarded() => Promise<void>

Pulls the next available Rewarded ad from the preload buffer and shows it instantly.

isRewardedPreloadAvailable(...)

isRewardedPreloadAvailable(options?: { adUnitId?: string | undefined; } | undefined) => Promise<{ isAvailable: boolean; }>

Synchronously checks if a Rewarded ad is ready in the preload buffer.

| Param | Type | | ------------- | ----------------------------------- | | options | { adUnitId?: string; } |

Returns: Promise<{ isAvailable: boolean; }>

startPreloadRewardedInterstitial(...)

startPreloadRewardedInterstitial(options: RewardedInterstitialOptions & { bufferSize?: number; }) => Promise<void>

Starts the background preloader buffer for Rewarded Interstitial Ads.

| Param | Type | | ------------- | -------------------------------------------------------------------------------------------------------------- | | options | RewardedInterstitialOptions & { bufferSize?: number; } |

pollAndShowRewardedInterstitial()

pollAndShowRewardedInterstitial() => Promise<void>

Pulls the next available Rewarded Interstitial ad from the preload buffer and shows it instantly.

isRewardedInterstitialPreloadAvailable(...)

isRewardedInterstitialPreloadAvailable(options?: { adUnitId?: string | undefined; } | undefined) => Promise<{ isAvailable: boolean; }>

Synchronously checks if a Rewarded Interstitial ad is ready in the preload buffer.

| Param | Type | | ------------- | ----------------------------------- | | options | { adUnitId?: string; } |

Returns: Promise<{ isAvailable: boolean; }>

addListener(string, ...)

addListener(eventName: string, listenerFunc: (info: any) => void) => Promise<PluginListenerHandle>

Listens for Ad events triggered by the native SDK.

💡 NOTE ON PRELOADING: If you are using the Next-Gen Preloading API, standard ad events (like Loaded, FailedToLoad, Impression, Paid, etc.) will include an additional property: { source: "preloader" }. This allows you to easily distinguish them from Classic API events using a single listener.
Interstitial Events

onInterstitialAdLoaded: Fired when an ad is loaded. Returns { adUnitId: string, source?: string }.
onInterstitialAdFailedToLoad: Fired when an ad fails to load. Returns { error: string, source?: string }.
onInterstitialAdShowed: Fired when an ad is displayed.
onInterstitialAdDismissed: Fired when an ad is closed by the user.
onInterstitialAdFailedToShow: Fired when an ad fails to display. Returns { error: string, source?: string }.
onInterstitialAdImpression: Fired when an ad impression is recorded.
onInterstitialAdClicked: Fired when an ad is clicked.
onInterstitialAdPaid: Fired when revenue is recorded. Returns AdPaidEvent.

Rewarded Events

onRewardedAdLoaded: Fired when an ad is loaded. Returns { adUnitId: string, source?: string }.
onRewardedAdFailedToLoad: Fired when an ad fails to load. Returns { error: string, source?: string }.
onRewardedAdShowed: Fired when an ad is displayed.
onRewardedAdDismissed: Fired when an ad is closed.
onRewardedAdFailedToShow: Fired when an ad fails to display. Returns { error: string, source?: string }.
onRewardedAdImpression: Fired when an ad impression is recorded.
onRewardedAdClicked: Fired when an ad is clicked.
onRewardedAdReward: Fired when the user earns a reward. Returns { amount: number, type: string, source?: string }.
onRewardedAdSkip: Fired when the user closes the ad before earning the reward.
onRewardedAdPaid: Fired when revenue is recorded. Returns AdPaidEvent.

Rewarded Interstitial Events

onRewardedInterstitialAdLoaded: Fired when an ad is loaded. Returns { adUnitId: string, source?: string }.
onRewardedInterstitialAdFailedToLoad: Fired when an ad fails to load. Returns { error: string, source?: string }.
onRewardedInterstitialAdShowed: Fired when an ad is displayed.
onRewardedInterstitialAdDismissed: Fired when an ad is closed.
onRewardedInterstitialAdFailedToShow: Fired when an ad fails to display. Returns { error: string, source?: string }.
onRewardedInterstitialAdImpression: Fired when an ad impression is recorded.
onRewardedInterstitialAdClicked: Fired when an ad is clicked.
onRewardedInterstitialAdReward: Fired when the user earns a reward. Returns { amount: number, type: string, source?: string }.
onRewardedInterstitialAdSkip: Fired when the user closes the ad before earning the reward interstitial.
onRewardedInterstitialAdPaid: Fired when revenue is recorded. Returns AdPaidEvent.

App Open Events

onAppOpenAdLoaded: Fired when an ad is loaded. Returns { adUnitId: string, source?: string }.
onAppOpenAdFailedToLoad: Fired when an ad fails to load. Returns { error: string, source?: string }.
onAppOpenAdShowed: Fired when an ad is displayed.
onAppOpenAdDismissed: Fired when an ad is closed.
onAppOpenAdFailedToShow: Fired when an ad fails to display. Returns { error: string, source?: string }.
onAppOpenAdImpression: Fired when an ad impression is recorded.
onAppOpenAdClicked: Fired when an ad is clicked.
onAppOpenAdPaid: Fired when revenue is recorded. Returns AdPaidEvent.

Banner Events

onBannerAdLoaded: Fired when a banner is loaded. Returns { adUnitId: string, width: number, height: number, widthPixels: number, heightPixels: number, isCollapsible: boolean, source?: string }.
onBannerAdFailedToLoad: Fired when a banner fails to load. Returns { error: string, source?: string }.
onBannerAdImpression: Fired when a banner impression is recorded.
onBannerAdClicked: Fired when a banner is clicked.
onBannerAdShowedFullScreen: Fired when a banner opens an overlay (e.g., user clicked it).
onBannerAdDismissedFullScreen: Fired when the banner overlay is closed.
onBannerAdFailedToShowFullScreen: Fired when the banner overlay fails to open. Returns { error: string, source?: string }.
onBannerAdRefreshed: Fired when the banner auto-refreshes.
onBannerAdFailedToRefresh: Fired when the banner auto-refresh fails. Returns { error: string, source?: string }.
onBannerAdPaid: Fired when revenue is recorded. Returns AdPaidEvent.
onBannerOrientationChanged: Fired when the device orientation changes while a banner is visible. Returns { adUnitId: string, orientation: "LANDSCAPE" | "PORTRAIT" }.

Native Events

onNativeAdLoaded: Fired when a native ad is successfully loaded and rendered. Returns { width: number, height: number }.
onNativeAdFailedToLoad: Fired when a native ad fails to load from the network. Returns { message: string }.
onNativeAdShowed: Fired when the native ad opens an overlay (e.g., user clicked to view full content).
onNativeAdDismissed: Fired when the native ad overlay is closed.
onNativeAdFailedToShow: Fired when the native ad fails to show full-screen content. Returns { message: string }.
onNativeAdImpression: Fired when a native ad impression is recorded.
onNativeAdClicked: Fired when a native ad is clicked by the user.
onNativeAdPaid: Fired when revenue is recorded. Returns AdPaidEvent.

Consent (UMP) Events

onConsentInfoUpdated: Fired when consent info is successfully updated.
onConsentFormDismissed: Fired when the consent form overlay is closed.
onConsentStatusChange: Fired when consent status changes. Returns ConsentStatusResult.
onConsentError: Fired when a UMP error occurs. Returns { code: number, message: string }.

Next-Gen Buffer Events (Exhausted)

These events are uniquely fired by the Preloading API when the background buffer runs out of cached ads.

onAppOpenAdPreloadExhausted: Fired when the App Open buffer is empty. Returns { adUnitId: string, source: "preloader" }.
onInterstitialAdPreloadExhausted: Fired when the Interstitial buffer is empty. Returns { adUnitId: string, source: "preloader" }.
onRewardedAdPreloadExhausted: Fired when the Rewarded buffer is empty. Returns { adUnitId: string, source: "preloader" }.
onRewardedInterstitialAdPreloadExhausted: Fired when the Rewarded Interstitial buffer is empty. Returns { adUnitId: string, source: "preloader" }.
onBannerAdPreloadExhausted: Fired when the Banner buffer is empty. Returns { adUnitId: string, source: "preloader" }.

@param eventName The name of the event to listen for.

| Param | Type | Description | | ------------------ | ----------------------------------- | ---------------------------------------------- | | eventName | string | | | listenerFunc | (info: any) => void | The callback function handling the event data. |

Returns: Promise<PluginListenerHandle>

Interfaces

TrackingAuthorizationResult

| Prop | Type | Description | | ------------ | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | status | 'authorized' | 'denied' | 'notDetermined' | 'restricted' | 'unknown' | The current status of the App Tracking Transparency (ATT) authorization. - authorized: The user authorized access to app-related data for tracking. - denied: The user denied authorization to access app-related data for tracking. - notDetermined: The user has not yet received an authorization request. - restricted: The authorization to access app-related data is restricted. - unknown: Platform does not support ATT (e.g., Android, Web, or older iOS). |

ConsentStatusResult

| Prop | Type | Description | | ------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | canRequestAds | boolean | Indicates whether you have obtained sufficient consent to safely request ads. Do not load ads if this is false. | | privacyOptionsRequirementStatus | string | The exact string representation of the privacy options requirement. Possible values: "REQUIRED", "NOT_REQUIRED", "UNKNOWN". | | isPrivacyOptionsRequired | boolean | A simplified boolean check for privacyOptionsRequirementStatus === 'REQUIRED'. If true, you MUST provide a button in your app's settings allowing the user to modify their privacy choices, which triggers showPrivacyOptionsForm(). | | consentStatus | number | The current consent status integer indicator: - 0 = UNKNOWN: Consent status is unknown. - 1 = REQUIRED: User consent is required but has not been obtained yet. - 2 = NOT_REQUIRED: User consent is not required (e.g., user is outside the EEA). - 3 = OBTAINED: User consent has been successfully obtained. |

ConsentOptions

| Prop | Type | Description | | ----------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | debug | boolean | Enables debug mode to simulate user location in the EEA (European Economic Area) for testing UMP. VERY IMPORTANT: Set to false in production. Default: false | | reset | boolean | Clears all previously saved consent data. Useful for simulating a first-time app launch. Default: false | | tagForUnderAgeOfConsent | boolean | Sets whether the user is under the age of consent for GDPR purposes. Default: false | | testDeviceId | string | A specific hashed device ID for debugging. If debug is true and this is left empty, the plugin will automatically attempt to detect and register the current device. |

TCDataResult

| Prop | Type | Description | | --------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | tcString | string | The raw Transparency and Consent String (TC String) encoded in Base64. | | purposeConsents | string | A binary string representing user consent for specific IAB purposes (e.g., "10011..."). Index 0 represents Purpose 1, index 1 represents Purpose 2, etc. | | vendorConsents | string | A binary string representing user consent for specific vendors. | | gdprApplies | number | Indicates whether GDPR applies to this user. - 1 = GDPR applies. - 0 = GDPR does not apply. | | isPersonalizedAllowed | boolean | A smart helper boolean parsed natively by the plugin. Returns true if IAB Purpose 1 is granted OR if GDPR does not apply. Useful for quickly deciding whether to load personalized or non-personalized ads manually. | | statusMessage | string | A human-readable message explaining the parsing result of the TCData. |

InitializeResult

| Prop | Type | | ------------ | ------------------- | | status | string |

InitializeOptions

| Prop | Type | Description | | ---------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | isTesting | boolean | Automatically detect and register the current device as a test device. VERY IMPORTANT: Set this to false or remove it before publishing your app to the Play Store. Default: false | | maxAdContentRating | '' | 'G' | 'PG' | 'T' | 'MA' | Filter ads by content rating. 'G': General audiences 'PG': Parental guidance 'T': Teens 'MA': Mature audiences Default: "" (No filter) | | tagForChildDirectedTreatment | boolean | For purposes of the Children's Online Privacy Protection Act (COPPA). true: Child-directed false: Not child-directed undefined: Unspecified | | tagForUnderAgeOfConsent | boolean | For users under the age of consent (GDPR). true: Under age of consent false: Not under age of consent undefined: Unspecified |

AppOpenOptions

| Prop | Type | Description | | ------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | adUnitId | string | | | retryInterval | number | Minimum time (in milliseconds) before the next ad request is allowed. Prevents spam requests and invalid traffic bans. Default is 5000. |

BannerOptions

| Prop | Type | Description | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | adUnitId | string | | | isAutoShow | boolean | Automatically show the banner after it successfully loads. Default is true. | | position | 'TOP' | 'BOTTOM' | "TOP" or "BOTTOM". Default is "BOTTOM". | | adSize | 'BANNER' | 'LARGE_BANNER' | 'MEDIUM_RECTANGLE' | 'FULL_BANNER' | 'LEADERBOARD' | 'LARGE_LANDSCAPE_ANCHORED_ADAPTIVE' | 'LARGE_PORTRAIT_ANCHORED_ADAPTIVE' | 'CURRENT_ORIENTATION_INLINE_ADAPTIVE' | 'LARGE_ANCHORED_ADAPTIVE' | 'PORTRAIT_INLINE_ADAPTIVE' | 'ADAPTIVE' | Specifies the banner size or adaptive behavior. Default is "ADAPTIVE" (Current Orientation Anchored Adaptive). | | isOverlap | boolean | If true, the banner overlaps the webview. If false, it pushes the webview up/down. Default is true. | | isCollapsible | boolean | Enables Google's collapsible banner feature. Default is false. | | retryInterval | number | Minimum time (in milliseconds) before the next ad request is allowed. Prevents spam requests and invalid traffic bans. Default is 5000. |

InterstitialOptions

RewardedOptions

RewardedInterstitialOptions

NativeAdOptions

| Prop | Type | Description | | ------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | adUnitId | string | | | template | 'small' | 'medium' | The name of the template to use (e.g., "small" or "medium"). Default is "small". | | x | number | The X coordinate on the screen where the ad should appear. ⚠️ IMPORTANT: Must be an integer (whole number). If calculating from DOM elements, use Math.round(). Default is 0. | | y | number | The Y coordinate on the screen where the ad should appear. ⚠️ IMPORTANT: Must be an integer (whole number). If calculating from DOM elements, use Math.round(). Default is 0. | | width | number | The width of the ad in density-independent pixels (dp/pt). ⚠️ IMPORTANT: Must be an integer (whole number). Use Math.round() if getting width from getBoundingClientRect(). If not provided, it defaults to matching the parent view's width (MATCH_PARENT). | | height | number | The height of the ad in density-independent pixels (dp/pt). Note: The height is usually constrained by the template type (e.g., Small is ~120, Medium is ~350). Default is WRAP_CONTENT. | | retryInterval | number | Minimum time (in milliseconds) before the next ad request is allowed. Prevents spam requests and invalid traffic bans. Default is 5000. |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

capacitor-admob-nextgen

📦 Current SDK Versions (Maintained & Up-to-Date)

✨ Key Features

🚀 Core & Performance

🧩 Banner Ads

📱 Full-Screen Ads (Interstitial, Rewarded, App Open)

⚠️ Important Notices

1. Built from Scratch with Battle-Tested Logic

2. Next-Gen SDK ONLY

📦 Installation

⚙️ Configuration (App ID Setup)

Option A: Automatic Setup (Highly Recommended)

Option B: Manual Setup

🧩 Native Ads Setup (Opt-In Feature)

🤝 Third-Party Mediation (Opt-In Feature)

🍎 Note: iOS (Capacitor 8+ & SPM)

Note: IOS

🚀 Example Usage

Install

API

AdMob Next-Gen Plugin

CRITICAL: Proper Execution Order

requestTrackingAuthorization()

requestConsentInfo(...)

showPrivacyOptionsForm()

getTCData()

initialize(...)

loadAppOpen(...)

showAppOpen()

createBanner(...)

showBanner()

hideBanner()

destroyBanner()

loadInterstitial(...)

showInterstitial()

loadRewarded(...)

showRewarded()

loadRewardedInterstitial(...)

showRewardedInterstitial()

showNativeAd(...)

hideNativeAd()

startPreloadAppOpen(...)

pollAndShowAppOpen()

isAppOpenPreloadAvailable(...)

startPreloadBanner(...)

pollAndShowBanner()

hidePreloadedBanner()

destroyPreloadedBanner()

isBannerPreloadAvailable(...)

startPreloadInterstitial(...)

pollAndShowInterstitial()

isInterstitialPreloadAvailable(...)

startPreloadRewarded(...)

pollAndShowRewarded()

isRewardedPreloadAvailable(...)

startPreloadRewardedInterstitial(...)

pollAndShowRewardedInterstitial()

isRewardedInterstitialPreloadAvailable(...)

addListener(string, ...)

Interstitial Events

Rewarded Events

Rewarded Interstitial Events

App Open Events

Banner Events

Native Events

Consent (UMP) Events

Next-Gen Buffer Events (Exhausted)

Interfaces

TrackingAuthorizationResult

ConsentStatusResult

ConsentOptions

TCDataResult

InitializeResult

InitializeOptions