@capgo/capacitor-admob

Show Google AdMob ads in your Capacitor app on iOS and Android: banner, interstitial, rewarded and rewarded interstitial formats from one TypeScript API. Monetize your app with the official Google Mobile Ads SDKs underneath.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-admob in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-admob to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Four ad formats: BannerAd, InterstitialAd, RewardedAd and RewardedInterstitialAd classes with load and show, plus hide() on BannerAd.
• Ad lifecycle: adCreate(), adLoad(), adIsLoaded(), adShow() and adHide() give you full control over each ad instance.
• SDK setup: start() initializes AdMob, configure() sets app-wide options and configRequest() sets request options.
• App Tracking Transparency: trackingAuthorizationStatus() and requestTrackingAuthorization() handle the iOS tracking prompt.
• Current SDKs: Google Mobile Ads Next Gen SDK on Android and Google Mobile Ads SDK on iOS.
• Platforms: iOS and Android. The web implementation is a no-op stub.

AdMob SDK bridge for Capacitor apps

Android now uses the Google Mobile Ads Next Gen SDK, and iOS is aligned to Google Mobile Ads SDK 13.1.x, while preserving the existing Capacitor-facing API.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/admob/

Compatibility

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-admob` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capgo/capacitor-admob
npx cap sync

Consent (UMP)

For apps serving users in the EEA/UK, request consent with Google's User Messaging Platform (UMP) before loading ads. Configure GDPR messages in your AdMob account first.

import { AdMob, AdmobConsentStatus } from '@capgo/capacitor-admob';

await AdMob.start();

let consentInfo = await AdMob.requestConsentInfo();
if (consentInfo.isConsentFormAvailable && consentInfo.status === AdmobConsentStatus.REQUIRED) {
  consentInfo = await AdMob.showConsentForm();
}

if (consentInfo.canRequestAds) {
  // Load ads only after consent allows ad requests.
}

To let users manage privacy choices later, call showPrivacyOptionsForm() from a settings screen when privacyOptionsRequirementStatus is REQUIRED.

For local testing on a real device, pass debugGeography and testDeviceIdentifiers to requestConsentInfo().

API

• start()
• configure(...)
• configRequest(...)
• requestConsentInfo(...)
• showConsentForm()
• showPrivacyOptionsForm()
• adCreate(...)
• adIsLoaded(...)
• adLoad(...)
• adShow(...)
• adHide(...)
• feedAdCreate(...)
• feedAdDestroy(...)
• feedAdLoad(...)
• feedAdIsLoaded(...)
• feedAdUpdateBounds(...)
• feedAdSetAutoRefresh(...)
• trackingAuthorizationStatus()
• requestTrackingAuthorization()
• addListener(E, ...)
• getPluginVersion()
• Interfaces
• Type Aliases
• Enums

AdMob Plus Plugin interface for displaying Google AdMob ads in Capacitor apps.

start()

start() => Promise<void>

Initialize and start the AdMob SDK.

Since: 1.0.0

configure(...)

configure(config: AdMobConfig) => Promise<void>

Configure AdMob settings.

Since: 1.0.0

configRequest(...)

configRequest(requestConfig: RequestConfig) => Promise<void>

Configure ad request settings.

Since: 1.0.0

requestConsentInfo(...)

requestConsentInfo(options?: AdmobConsentRequestOptions | undefined) => Promise<AdmobConsentInfo>

Request user consent information from Google's User Messaging Platform (UMP).

Call this after start() and before loading ads for users in the EEA/UK.

Returns: Promise<AdmobConsentInfo>

Since: 8.2.0

showConsentForm()

showConsentForm() => Promise<AdmobConsentInfo>

Shows the Google user consent form rendered from your GDPR message configuration.

Returns: Promise<AdmobConsentInfo>

Since: 8.2.0

showPrivacyOptionsForm()

showPrivacyOptionsForm() => Promise<void>

Shows the Google privacy options form rendered from your GDPR message configuration.

Use this when your privacy message requires an in-app entry point for users to manage choices.

Since: 8.2.0

adCreate(...)

adCreate<O extends MobileAdOptions>(opts: O) => Promise<void>

Create a new ad instance.

Since: 1.0.0

adIsLoaded(...)

adIsLoaded(opts: { id: number; }) => Promise<boolean>

Check if an ad is loaded and ready to be shown.

Returns: Promise<boolean>

Since: 1.0.0

adLoad(...)

adLoad(opts: { id: number; }) => Promise<void>

Load an ad.

Since: 1.0.0

adShow(...)

adShow(opts: { id: number; }) => Promise<void>

Show a loaded ad.

Since: 1.0.0

adHide(...)

adHide(opts: { id: number; }) => Promise<void>

Hide a currently displayed ad.

Since: 1.0.0

feedAdCreate(...)

feedAdCreate(opts: FeedAdCreateOptions) => Promise<{ id: number; }>

Create an in-feed ad slot (native overlay or inline banner overlay).

Returns: Promise<{ id: number; }>

Since: 8.3.0

feedAdDestroy(...)

feedAdDestroy(opts: { id: number; }) => Promise<void>

Destroy a feed ad instance and remove its native overlay.

Since: 8.3.0

feedAdLoad(...)

feedAdLoad(opts: { id: number; }) => Promise<void>

Load or reload the feed ad. Listen for feed.load / feed.loadfail events.

Since: 8.3.0

feedAdIsLoaded(...)

feedAdIsLoaded(opts: { id: number; }) => Promise<boolean>

Whether the feed ad has finished loading.

Returns: Promise<boolean>

Since: 8.3.0

feedAdUpdateBounds(...)

feedAdUpdateBounds(opts: FeedAdBounds & { id: number; }) => Promise<void>

Position the native overlay over an HTML placeholder. Call on scroll, resize, and orientation changes.

Since: 8.3.0

feedAdSetAutoRefresh(...)

feedAdSetAutoRefresh(opts: { id: number; autoRefreshMs: number | null; }) => Promise<void>

Enable or disable auto-refresh (minimum 30 seconds).

Since: 8.3.0

trackingAuthorizationStatus()

trackingAuthorizationStatus() => Promise<{ status: TrackingAuthorizationStatus | false; }>

Get the current tracking authorization status (iOS only).

Returns: Promise<{ status: false | TrackingAuthorizationStatus; }>

Since: 1.0.0

requestTrackingAuthorization()

requestTrackingAuthorization() => Promise<{ status: TrackingAuthorizationStatus | false; }>

Request tracking authorization from the user (iOS only).

Returns: Promise<{ status: false | TrackingAuthorizationStatus; }>

Since: 1.0.0

addListener(E, ...)

addListener<E extends AdMobPlusEventName>(eventName: E, listenerFunc: (event: AdMobPlusEventPayloadMap[E]) => void) => Promise<PluginListenerHandle> & PluginListenerHandle

Add a listener for ad events.

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

Since: 1.0.0

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the native Capacitor plugin version.

Returns: Promise<{ version: string; }>

Since: 1.0.0

Interfaces

PluginListenerHandle

Type Aliases

AdMobConfig

Configuration options for AdMob.

{ /** Whether the app should be muted / appMuted?: boolean; /* The app volume (0.0 to 1.0) */ appVolume?: number; }

RequestConfig

Configuration for ad requests.

{ /** Maximum ad content rating / maxAdContentRating?: MaxAdContentRating; /* Whether to use the same app key / sameAppKey?: boolean; /* Tag for child-directed treatment (true, false, or null for unspecified) / tagForChildDirectedTreatment?: boolean | null; /* Tag for under age of consent (true, false, or null for unspecified) / tagForUnderAgeOfConsent?: boolean | null; /* Array of test device IDs */ testDeviceIds?: string[]; }

AdmobConsentInfo

Consent information returned by UMP.

{ /** The consent status of the user. / status: AdmobConsentStatus; /* If true, a consent form is available. / isConsentFormAvailable?: boolean; /* If true, an ad request can be made. / canRequestAds: boolean; /* Privacy options requirement status of the user. */ privacyOptionsRequirementStatus: PrivacyOptionsRequirementStatus; }

AdmobConsentRequestOptions

Options for requesting UMP consent information.

{ /** Sets the debug geography to test consent locally. / debugGeography?: AdmobConsentDebugGeography; /* * Test device IDs to allow for consent debugging. * On iOS, the ID may change if you uninstall and reinstall the app. / testDeviceIdentifiers?: string[]; /* * When true, tags the user as under the age of consent for UMP requests. * * @default false */ tagForUnderAgeOfConsent?: boolean; }

MobileAdOptions

Base options for mobile ads.

{ /** The ad unit ID from AdMob */ adUnitId: string; }

FeedAdCreateOptions

Options for creating an in-feed ad instance.

Policy: AdMob counts native impressions and clicks only when assets render inside {@link https://developers.google.com/admob/android/native/advanced | NativeAdView} / GADNativeAdView with the AdChoices icon and an ad attribution badge. This plugin overlays a compliant native view on your placeholder. Optional {@link FeedNativeAdAssets} are returned on feed.load for layout sizing only, not for manual click forwarding.

{ /** Native advanced or inline banner. / format: FeedAdFormat; /* AdMob ad unit ID. / adUnitId: string; /* Optional key echoed on feed events for your feed slot. / positionKey?: string; /* * Auto-refresh interval in milliseconds. AdMob requires at least 30 seconds. * Omit or pass null to disable auto-refresh. / autoRefreshMs?: number | null; /* Template colors when format is native. */ nativeStyle?: FeedNativeAdStyle; }

FeedAdFormat

In-feed ad format. Both use a native overlay aligned to an HTML placeholder.

'native' | 'banner'

FeedNativeAdStyle

Optional colors for the built-in native ad template (hex strings, e.g. #ffffff).

{ backgroundColor?: string; headlineTextColor?: string; bodyTextColor?: string; ctaBackgroundColor?: string; ctaTextColor?: string; }

FeedAdBounds

Bounds of the HTML placeholder, in CSS pixels relative to the WebView viewport.

{ x: number; y: number; width: number; height: number; /** When false, the native overlay is hidden (e.g. off-screen while scrolling). / visible: boolean; /* window.devicePixelRatio from the WebView. Defaults to 1 on web. */ density?: number; }

AdMobPlusEventName

(typeof AdMobPlusEvents)[keyof typeof AdMobPlusEvents]

AdMobPlusEventPayloadMap

Maps each {@link AdMobPlusEventName} to the payload shape emitted from native code.

{ [AdMobPlusEvents.AdClick]: AdMobPlusAdIdPayload; [AdMobPlusEvents.AdDismiss]: AdMobPlusAdIdPayload; [AdMobPlusEvents.AdImpression]: AdMobPlusAdIdPayload; [AdMobPlusEvents.AdLoad]: AdMobPlusAdIdPayload; [AdMobPlusEvents.AdLoadFail]: AdMobPlusAdFailurePayload; [AdMobPlusEvents.AdReward]: AdMobPlusAdRewardPayload; [AdMobPlusEvents.AdShow]: AdMobPlusAdIdPayload; [AdMobPlusEvents.AdShowFail]: AdMobPlusAdFailurePayload; [AdMobPlusEvents.BannerClick]: AdMobPlusAdIdPayload; [AdMobPlusEvents.BannerClose]: AdMobPlusAdIdPayload; [AdMobPlusEvents.BannerImpression]: AdMobPlusAdIdPayload; [AdMobPlusEvents.BannerLoad]: AdMobPlusAdIdPayload; [AdMobPlusEvents.BannerLoadFail]: AdMobPlusAdFailurePayload; [AdMobPlusEvents.BannerOpen]: AdMobPlusAdIdPayload; [AdMobPlusEvents.BannerSizeChange]: AdMobPlusAdIdPayload; [AdMobPlusEvents.InterstitialDismiss]: AdMobPlusAdIdPayload; [AdMobPlusEvents.InterstitialImpression]: AdMobPlusAdIdPayload; [AdMobPlusEvents.InterstitialLoad]: AdMobPlusAdIdPayload; [AdMobPlusEvents.InterstitialLoadFail]: AdMobPlusAdFailurePayload; [AdMobPlusEvents.InterstitialShow]: AdMobPlusAdIdPayload; [AdMobPlusEvents.InterstitialShowFail]: AdMobPlusAdFailurePayload; [AdMobPlusEvents.RewardedDismiss]: AdMobPlusAdIdPayload; [AdMobPlusEvents.RewardedImpression]: AdMobPlusAdIdPayload; [AdMobPlusEvents.RewardedInterstitialDismiss]: AdMobPlusAdIdPayload; [AdMobPlusEvents.RewardedInterstitialImpression]: AdMobPlusAdIdPayload; [AdMobPlusEvents.RewardedInterstitialLoad]: AdMobPlusAdIdPayload; [AdMobPlusEvents.RewardedInterstitialLoadFail]: AdMobPlusAdFailurePayload; [AdMobPlusEvents.RewardedInterstitialReward]: AdMobPlusAdRewardPayload; [AdMobPlusEvents.RewardedInterstitialShow]: AdMobPlusAdIdPayload; [AdMobPlusEvents.RewardedInterstitialShowFail]: AdMobPlusAdFailurePayload; [AdMobPlusEvents.RewardedLoad]: AdMobPlusAdIdPayload; [AdMobPlusEvents.RewardedLoadFail]: AdMobPlusAdFailurePayload; [AdMobPlusEvents.RewardedReward]: AdMobPlusAdRewardPayload; [AdMobPlusEvents.RewardedShow]: AdMobPlusAdIdPayload; [AdMobPlusEvents.RewardedShowFail]: AdMobPlusAdFailurePayload; [AdMobPlusEvents.FeedClick]: AdMobPlusFeedAdIdPayload; [AdMobPlusEvents.FeedClose]: AdMobPlusFeedAdIdPayload; [AdMobPlusEvents.FeedImpression]: AdMobPlusFeedAdIdPayload; [AdMobPlusEvents.FeedLoad]: AdMobPlusFeedLoadPayload; [AdMobPlusEvents.FeedLoadFail]: AdMobPlusAdFailurePayload & AdMobPlusFeedAdIdPayload; [AdMobPlusEvents.FeedOpen]: AdMobPlusFeedAdIdPayload; [AdMobPlusEvents.FeedRefresh]: AdMobPlusFeedAdIdPayload; }

AdMobPlusAdIdPayload

Event payload always includes the native ad instance id (adId). iOS also emits legacy id.

{ adId: number; id?: number; }

AdMobPlusAdFailurePayload

Load and fullscreen show failure payloads from native LoadAdError / FullScreenContentError.

AdMobPlusAdIdPayload & { code: number; message: string; /** Legacy iOS failure field; same string as message when present. */ error?: string; }

AdMobPlusAdRewardPayload

Reward callbacks include the earned reward plus adId.

AdMobPlusAdIdPayload & { reward: { amount: number; type: string; }; }

AdMobPlusFeedAdIdPayload

In-feed ad events use feedAdId (same numeric id as feedAdCreate).

{ feedAdId: number; positionKey?: string; format?: 'native' | 'banner'; }

AdMobPlusFeedLoadPayload

AdMobPlusFeedAdIdPayload & { assets?: Record<string, unknown>; }

Record

Construct a type with a set of properties K of type T

{ [P in K]: T; }

Enums

MaxAdContentRating

AdmobConsentStatus

PrivacyOptionsRequirementStatus

AdmobConsentDebugGeography

TrackingAuthorizationStatus