@capacitor-community/admob v6.0.0

Maintainers

Maintenance Status: Actively Maintained

Contributors ✨

Made with contributors-img.

Demo

Demo code is here.

Screenshots

	Banner	Interstitial	Reward
iOS
Android

Installation

If you use capacitor 5:

% npm install --save @capacitor-community/admob@5.0.0
% npx cap update

If you use capacitor 4:

% npm install --save @capacitor-community/admob@4.0.0
% npx cap update

capacitor 3:

% npm install --save @capacitor-community/admob@3.3.0
% npx cap update

Android configuration

In file android/app/src/main/AndroidManifest.xml, add the following XML elements under <manifest><application> :

<meta-data
 android:name="com.google.android.gms.ads.APPLICATION_ID"
 android:value="@string/admob_app_id"/>

In file android/app/src/main/res/values/strings.xml add the following lines :

<string name="admob_app_id">[APP_ID]</string>

Don't forget to replace [APP_ID] by your AdMob application Id.

Variables

This plugin will use the following project variables (defined in your app's variables.gradle file):

• playServicesAdsVersion version of com.google.android.gms:play-services-ads (default: 22.0.0)
• androidxCoreKTXVersion: version of androidx.core:core-ktx (default: 1.10.0)

iOS configuration

Add the following in the ios/App/App/info.plist file inside of the outermost <dict>:

<key>GADIsAdManagerApp</key>
<true/>
<key>GADApplicationIdentifier</key>
<string>[APP_ID]</string>
<key>SKAdNetworkItems</key>
<array>
  <dict>
    <key>SKAdNetworkIdentifier</key>
    <string>cstr6suwn9.skadnetwork</string>
  </dict>
</array>
<key>NSUserTrackingUsageDescription</key>
<string>[Why you use NSUserTracking. ex: This identifier will be used to deliver personalized ads to you.]</string>

Don't forget to replace [APP_ID] by your AdMob application Id.

Example

Initialize AdMob

import { AdMob } from '@capacitor-community/admob';

export async function initialize(): Promise<void> {
  await AdMob.initialize();
 
  const [trackingInfo, consentInfo] = await Promise.all([
   AdMob.trackingAuthorizationStatus(),
   AdMob.requestConsentInfo(),
  ]);
 
  if (trackingInfo.status === 'notDetermined') {
   /**
    * If you want to explain TrackingAuthorization before showing the iOS dialog,
    * you can show the modal here.
    * ex)
    * const modal = await this.modalCtrl.create({
    *   component: RequestTrackingPage,
    * });
    * await modal.present();
    * await modal.onDidDismiss();  // Wait for close modal
    **/
 
   await AdMob.requestTrackingAuthorization();
  }

  const authorizationStatus = await AdMob.trackingAuthorizationStatus();
  if (
          authorizationStatus.status === 'authorized' &&
          consentInfo.isConsentFormAvailable &&
          consentInfo.status === AdmobConsentStatus.REQUIRED
  ) {
   await AdMob.showConsentForm();
  }
}

Send and array of device Ids in `testingDevices? to use production like ads on your specified devices -> https://developers.google.com/admob/android/test-ads#enable_test_devices

User Message Platform (UMP)

Later this year, Google will require all publishers serving ads to EEA and UK users to use a Google-certified Consent Management Platform (CMP)

Currently we just support Google's consent management solution.

To use UMP, you must create your GDPR messages

You may need to setup IDFA messages, it will work along with GDPR messages and will show when users are not in EEA and UK.

Example of how to use UMP

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

async showConsent() {
  const consentInfo = await AdMob.requestConsentInfo();

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

If you testing on real device, you have to set debugGeography and add your device ID to testDeviceIdentifiers. You can find your device ID with logcat (Android) or XCode (iOS).

  const consentInfo = await AdMob.requestConsentInfo({
    debugGeography: AdmobConsentDebugGeography.EEA,
    testDeviceIdentifiers: ['YOUR_DEVICE_ID']
  });

Note: When testing, if you choose not consent (Manage -> Confirm Choices). The ads may not load/show. Even on testing enviroment. This is normal. It will work on Production so don't worry.

Note: The order in which they are combined with other methods is as follows.

1. AdMob.initialize
2. AdMob.requestConsentInfo
3. AdMob.showConsentForm (If consent form required ) 3/ AdMob.showBanner

Show Banner

import { AdMob, BannerAdOptions, BannerAdSize, BannerAdPosition, BannerAdPluginEvents, AdMobBannerSize } from '@capacitor-community/admob';

export async function banner(): Promise<void> {
    AdMob.addListener(BannerAdPluginEvents.Loaded, () => {
      // Subscribe Banner Event Listener
    });

    AdMob.addListener(BannerAdPluginEvents.SizeChanged, (size: AdMobBannerSize) => {
      // Subscribe Change Banner Size
    });

    const options: BannerAdOptions = {
      adId: 'YOUR ADID',
      adSize: BannerAdSize.BANNER,
      position: BannerAdPosition.BOTTOM_CENTER,
      margin: 0,
      // isTesting: true
      // npa: true
    };
    AdMob.showBanner(options);
}

Show Interstitial

import { AdMob, AdOptions, AdLoadInfo, InterstitialAdPluginEvents } from '@capacitor-community/admob';

export async function interstitial(): Promise<void> {
  AdMob.addListener(InterstitialAdPluginEvents.Loaded, (info: AdLoadInfo) => {
    // Subscribe prepared interstitial
  });

  const options: AdOptions = {
    adId: 'YOUR ADID',
    // isTesting: true
    // npa: true
  };
  await AdMob.prepareInterstitial(options);
  await AdMob.showInterstitial();
}

Show RewardVideo

import { AdMob, RewardAdOptions, AdLoadInfo, RewardAdPluginEvents, AdMobRewardItem } from '@capacitor-community/admob';

export async function rewardVideo(): Promise<void> {
  AdMob.addListener(RewardAdPluginEvents.Loaded, (info: AdLoadInfo) => {
    // Subscribe prepared rewardVideo
  });

  AdMob.addListener(RewardAdPluginEvents.Rewarded, (rewardItem: AdMobRewardItem) => {
    // Subscribe user rewarded
    console.log(rewardItem);
  });

  const options: RewardAdOptions = {
    adId: 'YOUR ADID',
    // isTesting: true
    // npa: true
    // ssv: {
    //   userId: "A user ID to send to your SSV"
    //   customData: JSON.stringify({ ...MyCustomData })
    //}
  };
  await AdMob.prepareRewardVideoAd(options);
  const rewardItem = await AdMob.showRewardVideoAd();
}

Server-side Verification Notice

SSV callbacks are only fired on Production Adverts, therefore test Ads will not fire off your SSV callback.

For E2E tests or just for validating the data in your RewardAdOptions work as expected, you can add a custom GET request to your mock endpoint after the RewardAdPluginEvents.Rewarded similar to this:

AdMob.addListener(RewardAdPluginEvents.Rewarded, async () => {
  // ...
  if (ENVIRONMENT_IS_DEVELOPMENT) {
    try {
      const url = `https://your-staging-ssv-endpoint` + new URLSearchParams({
        'ad_network': 'TEST',
        'ad_unit': 'TEST',
        'custom_data': customData, // <-- passed CustomData
        'reward_amount': 'TEST',
        'reward_item': 'TEST',
        'timestamp': 'TEST',
        'transaction_id': 'TEST',
        'user_id': userId, // <-- Passed UserID
        'signature': 'TEST',
        'key_id': 'TEST'
      });
      await fetch(url);
    } catch (err) {
      console.error(err);
    }
  }
  // ...
});

Index

• initialize(...)
• trackingAuthorizationStatus()
• requestTrackingAuthorization()
• setApplicationMuted(...)
• setApplicationVolume(...)
• showBanner(...)
• hideBanner()
• resumeBanner()
• removeBanner()
• addListener(BannerAdPluginEvents.SizeChanged, ...)
• addListener(BannerAdPluginEvents.Loaded, ...)
• addListener(BannerAdPluginEvents.FailedToLoad, ...)
• addListener(BannerAdPluginEvents.Opened, ...)
• addListener(BannerAdPluginEvents.Closed, ...)
• addListener(BannerAdPluginEvents.AdImpression, ...)
• requestConsentInfo(...)
• showConsentForm()
• resetConsentInfo()
• prepareInterstitial(...)
• showInterstitial()
• addListener(InterstitialAdPluginEvents.FailedToLoad, ...)
• addListener(InterstitialAdPluginEvents.Loaded, ...)
• addListener(InterstitialAdPluginEvents.Dismissed, ...)
• addListener(InterstitialAdPluginEvents.FailedToShow, ...)
• addListener(InterstitialAdPluginEvents.Showed, ...)
• prepareRewardVideoAd(...)
• showRewardVideoAd()
• addListener(RewardAdPluginEvents.FailedToLoad, ...)
• addListener(RewardAdPluginEvents.Loaded, ...)
• addListener(RewardAdPluginEvents.Rewarded, ...)
• addListener(RewardAdPluginEvents.Dismissed, ...)
• addListener(RewardAdPluginEvents.FailedToShow, ...)
• addListener(RewardAdPluginEvents.Showed, ...)
• Interfaces
• Type Aliases
• Enums

API

initialize(...)

initialize(options?: AdMobInitializationOptions) => Promise<void>

Initialize AdMob with AdMobInitializationOptions

trackingAuthorizationStatus()

trackingAuthorizationStatus() => Promise<TrackingAuthorizationStatusInterface>

Confirm requestTrackingAuthorization status (iOS >14)

Returns: Promise<TrackingAuthorizationStatusInterface>

requestTrackingAuthorization()

requestTrackingAuthorization() => Promise<void>

request requestTrackingAuthorization (iOS >14). This is deprecated method. We recommend UMP Consent.

setApplicationMuted(...)

setApplicationMuted(options: ApplicationMutedOptions) => Promise<void>

Report application mute state to AdMob SDK

setApplicationVolume(...)

setApplicationVolume(options: ApplicationVolumeOptions) => Promise<void>

Report application volume to AdMob SDK

showBanner(...)

showBanner(options: BannerAdOptions) => Promise<void>

Show a banner Ad

hideBanner()

hideBanner() => Promise<void>

Hide the banner, remove it from screen, but can show it later

resumeBanner()

resumeBanner() => Promise<void>

Resume the banner, show it after hide

removeBanner()

removeBanner() => Promise<void>

Destroy the banner, remove it from screen.

addListener(BannerAdPluginEvents.SizeChanged, ...)

addListener(eventName: BannerAdPluginEvents.SizeChanged, listenerFunc: (info: AdMobBannerSize) => void) => Promise<PluginListenerHandle>

Returns: Promise<PluginListenerHandle>

addListener(BannerAdPluginEvents.Loaded, ...)

addListener(eventName: BannerAdPluginEvents.Loaded, listenerFunc: () => void) => Promise<PluginListenerHandle>

Notice: request loaded Banner ad

Returns: Promise<PluginListenerHandle>

addListener(BannerAdPluginEvents.FailedToLoad, ...)

addListener(eventName: BannerAdPluginEvents.FailedToLoad, listenerFunc: (info: AdMobError) => void) => Promise<PluginListenerHandle>

Notice: request failed Banner ad

Returns: Promise<PluginListenerHandle>

addListener(BannerAdPluginEvents.Opened, ...)

addListener(eventName: BannerAdPluginEvents.Opened, listenerFunc: () => void) => Promise<PluginListenerHandle>

Notice: full-screen banner view will be presented in response to the user clicking on an ad.

Returns: Promise<PluginListenerHandle>

addListener(BannerAdPluginEvents.Closed, ...)

addListener(eventName: BannerAdPluginEvents.Closed, listenerFunc: () => void) => Promise<PluginListenerHandle>

Notice: The full-screen banner view will been dismissed.

Returns: Promise<PluginListenerHandle>

addListener(BannerAdPluginEvents.AdImpression, ...)

addListener(eventName: BannerAdPluginEvents.AdImpression, listenerFunc: () => void) => Promise<PluginListenerHandle>

Unimplemented

Returns: Promise<PluginListenerHandle>

requestConsentInfo(...)

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

Request user consent information

Returns: Promise<AdmobConsentInfo>

showConsentForm()

showConsentForm() => Promise<AdmobConsentInfo>

Shows a google user consent form (rendered from your GDPR message config).

Returns: Promise<AdmobConsentInfo>

resetConsentInfo()

resetConsentInfo() => Promise<void>

Resets the UMP SDK state. Call requestConsentInfo function again to allow user modify their consent

prepareInterstitial(...)

prepareInterstitial(options: AdOptions) => Promise<AdLoadInfo>

Prepare interstitial banner

Returns: Promise<AdLoadInfo>

showInterstitial()

showInterstitial() => Promise<void>

Show interstitial ad when it’s ready

addListener(InterstitialAdPluginEvents.FailedToLoad, ...)

addListener(eventName: InterstitialAdPluginEvents.FailedToLoad, listenerFunc: (error: AdMobError) => void) => Promise<PluginListenerHandle>

Returns: Promise<PluginListenerHandle>

addListener(InterstitialAdPluginEvents.Loaded, ...)

addListener(eventName: InterstitialAdPluginEvents.Loaded, listenerFunc: (info: AdLoadInfo) => void) => Promise<PluginListenerHandle>

Returns: Promise<PluginListenerHandle>

addListener(InterstitialAdPluginEvents.Dismissed, ...)

addListener(eventName: InterstitialAdPluginEvents.Dismissed, listenerFunc: () => void) => Promise<PluginListenerHandle>

Returns: Promise<PluginListenerHandle>

addListener(InterstitialAdPluginEvents.FailedToShow, ...)

addListener(eventName: InterstitialAdPluginEvents.FailedToShow, listenerFunc: (error: AdMobError) => void) => Promise<PluginListenerHandle>

Returns: Promise<PluginListenerHandle>

addListener(InterstitialAdPluginEvents.Showed, ...)

addListener(eventName: InterstitialAdPluginEvents.Showed, listenerFunc: () => void) => Promise<PluginListenerHandle>

Returns: Promise<PluginListenerHandle>

prepareRewardVideoAd(...)

prepareRewardVideoAd(options: RewardAdOptions) => Promise<AdLoadInfo>

Prepare a reward video ad

Returns: Promise<AdLoadInfo>

showRewardVideoAd()

showRewardVideoAd() => Promise<AdMobRewardItem>

Show a reward video ad

Returns: Promise<AdMobRewardItem>

addListener(RewardAdPluginEvents.FailedToLoad, ...)

addListener(eventName: RewardAdPluginEvents.FailedToLoad, listenerFunc: (error: AdMobError) => void) => Promise<PluginListenerHandle>

Returns: Promise<PluginListenerHandle>

addListener(RewardAdPluginEvents.Loaded, ...)

addListener(eventName: RewardAdPluginEvents.Loaded, listenerFunc: (info: AdLoadInfo) => void) => Promise<PluginListenerHandle>

Returns: Promise<PluginListenerHandle>

addListener(RewardAdPluginEvents.Rewarded, ...)

addListener(eventName: RewardAdPluginEvents.Rewarded, listenerFunc: (reward: AdMobRewardItem) => void) => Promise<PluginListenerHandle>

Returns: Promise<PluginListenerHandle>

addListener(RewardAdPluginEvents.Dismissed, ...)

addListener(eventName: RewardAdPluginEvents.Dismissed, listenerFunc: () => void) => Promise<PluginListenerHandle>

Returns: Promise<PluginListenerHandle>

addListener(RewardAdPluginEvents.FailedToShow, ...)

addListener(eventName: RewardAdPluginEvents.FailedToShow, listenerFunc: (error: AdMobError) => void) => Promise<PluginListenerHandle>

Returns: Promise<PluginListenerHandle>

addListener(RewardAdPluginEvents.Showed, ...)

addListener(eventName: RewardAdPluginEvents.Showed, listenerFunc: () => void) => Promise<PluginListenerHandle>

Returns: Promise<PluginListenerHandle>

Interfaces

AdMobInitializationOptions

TrackingAuthorizationStatusInterface

ApplicationMutedOptions

ApplicationVolumeOptions

BannerAdOptions

This interface extends AdOptions

PluginListenerHandle

AdMobBannerSize

When notice listener of OnAdLoaded, you can get banner size.

AdMobError

For more information https://developers.google.com/android/reference/com/google/android/gms/ads/AdError

AdmobConsentInfo

AdmobConsentRequestOptions

AdLoadInfo

AdOptions

RewardAdOptions

AdMobRewardItem

For more information https://developers.google.com/admob/android/rewarded-video-adapters?hl=en

Type Aliases

AtLeastOne

{K in keyof T: Pick<T, K>}keyof T

Pick

From T, pick a set of properties whose keys are in the union K

{ P in K: TP; }

Enums

MaxAdContentRating

BannerAdSize

BannerAdPosition

BannerAdPluginEvents

AdmobConsentStatus

AdmobConsentDebugGeography

InterstitialAdPluginEvents

RewardAdPluginEvents

TROUBLE SHOOTING

If you have error:

error Error running update: Analyzing dependencies ! CocoaPods could not find compatible versions for pod "Google-Mobile-Ads-SDK":

You should run pod repo update ;

License

Capacitor AdMob is MIT licensed.