AdMob

@capacitor-community/admob

Capacitor community plugin for native AdMob.

Maintainers

Maintainer	GitHub	Social	Sponsoring Company
Masahiko Sakakibara	rdlabo	@rdlabo	RELATION DESIGN LABO, GENERAL INC. ASSOCIATION
Saninn Salas Diaz	Saninn Salas Diaz	@SaninnSalas

Maintenance Status: Actively Maintained

Demo

Demo code is here.

Screenshots

	Banner	Interstitial	Reward
iOS
Android

Installation

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

Android configuration

In file android/app/src/main/java/**/**/MainActivity.java, add the plugin to the initialization list:

public class MainActivity extends BridgeActivity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        registerPlugin(com.getcapacitor.community.admob.AdMob.class);
    }
}

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.

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> {
  AdMob.initialize({
    requestTrackingAuthorization: true,
    testingDevices: ['2077ef9a63d2b398840261c8221a0c9b'],
    initializeForTesting: true,
  });
}

You can use option requestTrackingAuthorization. This change permission to require AppTrackingTransparency in iOS >= 14: https://developers.google.com/admob/ios/ios14

Default value is true. If you don't want to track, set requestTrackingAuthorization false.

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

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

Maintainers
Demo
- Screenshots
Installation
- Android configuration
- iOS configuration
Example
Server-side Verification Notice
Index
API
TROUBLE SHOOTING
- If you have error:
License
Contributors ✨

API

initialize(...)

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

Initialize AdMob with AdMobInitializationOptions

Param	Type	Description
`options`	`AdMobInitializationOptions`	AdMobInitializationOptions

trackingAuthorizationStatus()

trackingAuthorizationStatus() => Promise<TrackingAuthorizationStatusInterface>

Confirm requestTrackingAuthorization status (iOS >14)

Returns: Promise<TrackingAuthorizationStatusInterface>

showBanner(...)

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

Show a banner Ad

Param	Type	Description
`options`	`BannerAdOptions`	AdOptions

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) => PluginListenerHandle

Param	Type	Description
`eventName`	`BannerAdPluginEvents.SizeChanged`	bannerAdSizeChanged
`listenerFunc`	`(info: AdMobBannerSize) => void`

Param	Type	Description
`eventName`	`BannerAdPluginEvents.Loaded`	bannerAdLoaded
`listenerFunc`	`() => void`

Param	Type	Description
`eventName`	`BannerAdPluginEvents.FailedToLoad`	bannerAdFailedToLoad
`listenerFunc`	`(info: AdMobError) => void`

Param	Type	Description
`eventName`	`BannerAdPluginEvents.Opened`	bannerAdOpened
`listenerFunc`	`() => void`

Param	Type	Description
`eventName`	`BannerAdPluginEvents.Closed`	bannerAdClosed
`listenerFunc`	`() => void`

Param	Type	Description
`eventName`	`BannerAdPluginEvents.AdImpression`	AdImpression
`listenerFunc`	`() => void`

Members	Value	Description
`SizeChanged`	`"bannerAdSizeChanged"`
`Loaded`	`"bannerAdLoaded"`
`FailedToLoad`	`"bannerAdFailedToLoad"`
`Opened`	`"bannerAdOpened"`	Open "Adsense" Event after user click banner
`Closed`	`"bannerAdClosed"`	Close "Adsense" Event after user click banner
`AdImpression`	`"bannerAdImpression"`	Similarly, this method should be called when an impression is recorded for the ad by the mediated SDK.

Param	Type
`eventName`	`InterstitialAdPluginEvents.Loaded`
`listenerFunc`	`(info: AdLoadInfo) => void`

Param	Type
`eventName`	`InterstitialAdPluginEvents.Dismissed`
`listenerFunc`	`() => void`

Param	Type
`eventName`	`InterstitialAdPluginEvents.FailedToShow`
`listenerFunc`	`(error: AdMobError) => void`

Param	Type
`eventName`	`InterstitialAdPluginEvents.Showed`
`listenerFunc`	`() => void`

Prop	Type	Description
`requestTrackingAuthorization`	`boolean`	Use or not requestTrackingAuthorization in iOS(>14)
`testingDevices`	`string[]`	An Array of devices IDs that will be marked as tested devices if {@link AdMobInitializationOptions.initializeForTesting} is true (Real Ads will be served to Testing devices but they will not count as 'real').
`initializeForTesting`	`boolean`	If set to true, the devices on {@link AdMobInitializationOptions.testingDevices} will be registered to receive test production ads.
`tagForChildDirectedTreatment`	`boolean`	For purposes of the Children's Online Privacy Protection Act (COPPA), there is a setting called tagForChildDirectedTreatment.
`tagForUnderAgeOfConsent`	`boolean`	When using this feature, a Tag For Users under the Age of Consent in Europe (TFUA) parameter will be included in all future ad requests.
`maxAdContentRating`	`MaxAdContentRating`	WAs an app developer, you can indicate whether you want Google to treat your content as child-directed when you make an ad request.

Prop	Type	Description
`adSize`	`BannerAdSize`	Banner Ad Size, defaults to ADAPTIVE_BANNER. IT can be: ADAPTIVE_BANNER, SMART_BANNER, BANNER, MEDIUM_RECTANGLE, FULL_BANNER, LEADERBOARD
`position`	`BannerAdPosition`	Set Banner Ad position. TOP_CENTER or CENTER or BOTTOM_CENTER

Prop	Type
`width`	`number`
`height`	`number`

Prop	Type	Description
`code`	`number`	Gets the error's code.
`message`	`string`	Gets the message describing the error.

Param	Type
`eventName`	`RewardAdPluginEvents.FailedToLoad`
`listenerFunc`	`(error: AdMobError) => void`

Param	Type
`eventName`	`RewardAdPluginEvents.Loaded`
`listenerFunc`	`(info: AdLoadInfo) => void`

Param	Type
`eventName`	`RewardAdPluginEvents.Rewarded`
`listenerFunc`	`(reward: AdMobRewardItem) => void`

Param	Type
`eventName`	`RewardAdPluginEvents.Dismissed`
`listenerFunc`	`() => void`

Param	Type
`eventName`	`RewardAdPluginEvents.FailedToShow`
`listenerFunc`	`(error: AdMobError) => void`

Param	Type
`eventName`	`RewardAdPluginEvents.Showed`
`listenerFunc`	`() => void`

Prop	Type	Description
`adId`	`string`	The ad unit ID that you want to request
`isTesting`	`boolean`	You can use test mode of ad.
`margin`	`number`	Margin Banner. Default is 0px; If position is BOTTOM_CENTER, margin is be margin-bottom. If position is TOP_CENTER, margin is be margin-top.
`npa`	`boolean`	The default behavior of the Google Mobile Ads SDK is to serve personalized ads. Set this to true to request Non-Personalized Ads

Prop	Type	Description
`type`	`string`	Rewarded type user got
`amount`	`number`	Rewarded amount user got

Members	Value	Description
`General`	`'General'`	Content suitable for general audiences, including families.
`ParentalGuidance`	`'ParentalGuidance'`	Content suitable for most audiences with parental guidance.
`Teen`	`'Teen'`	Content suitable for teen and older audiences.
`MatureAudience`	`'MatureAudience'`	Content suitable only for mature audiences.

Members	Value	Description
`BANNER`	`'BANNER'`	Mobile Marketing Association (MMA) banner ad size (320x50 density-independent pixels).
`FULL_BANNER`	`'FULL_BANNER'`	Interactive Advertising Bureau (IAB) full banner ad size (468x60 density-independent pixels).
`LARGE_BANNER`	`'LARGE_BANNER'`	Large banner ad size (320x100 density-independent pixels).
`MEDIUM_RECTANGLE`	`'MEDIUM_RECTANGLE'`	Interactive Advertising Bureau (IAB) medium rectangle ad size (300x250 density-independent pixels).
`LEADERBOARD`	`'LEADERBOARD'`	Interactive Advertising Bureau (IAB) leaderboard ad size (728x90 density-independent pixels).
`ADAPTIVE_BANNER`	`'ADAPTIVE_BANNER'`	A dynamically sized banner that is full-width and auto-height.
`SMART_BANNER`	`'SMART_BANNER'`

Files

README.md

Latest commit

History

README.md

File metadata and controls

AdMob

Maintainers

Demo

Screenshots

Installation

Android configuration

iOS configuration

Example

Initialize AdMob

Show Banner

Show Interstitial

Show RewardVideo

Server-side Verification Notice

Index

API

initialize(...)

trackingAuthorizationStatus()

showBanner(...)

hideBanner()

resumeBanner()

removeBanner()

addListener(BannerAdPluginEvents.SizeChanged, ...)

addListener(BannerAdPluginEvents.Loaded, ...)

addListener(BannerAdPluginEvents.FailedToLoad, ...)

addListener(BannerAdPluginEvents.Opened, ...)

addListener(BannerAdPluginEvents.Closed, ...)

addListener(BannerAdPluginEvents.AdImpression, ...)

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

AdMobInitializationOptions

TrackingAuthorizationStatusInterface

BannerAdOptions

PluginListenerHandle

AdMobBannerSize

AdMobError

AdLoadInfo

AdOptions

RewardAdOptions

AdMobRewardItem

Enums

MaxAdContentRating

BannerAdSize

BannerAdPosition

BannerAdPluginEvents

InterstitialAdPluginEvents

RewardAdPluginEvents

TROUBLE SHOOTING

If you have error:

License

Contributors ✨

Members	Value	Description
`TOP_CENTER`	`'TOP_CENTER'`	Banner position be top-center
`CENTER`	`'CENTER'`	Banner position be center
`BOTTOM_CENTER`	`'BOTTOM_CENTER'`	Banner position be bottom-center(default)

Members	Value	Description
`Loaded`	`'interstitialAdLoaded'`	Emits after trying to prepare and Interstitial, when it is loaded and ready to be show
`FailedToLoad`	`'interstitialAdFailedToLoad'`	Emits after trying to prepare and Interstitial, when it could not be loaded
`Showed`	`'interstitialAdShowed'`	Emits when the Interstitial ad is visible to the user
`FailedToShow`	`'interstitialAdFailedToShow'`	Emits when the Interstitial ad is failed to show
`Dismissed`	`'interstitialAdDismissed'`	Emits when the Interstitial ad is not visible to the user anymore.

Members	Value	Description
`Loaded`	`'onRewardedVideoAdLoaded'`	Emits after trying to prepare a RewardAd and the Video is loaded and ready to be show
`FailedToLoad`	`'onRewardedVideoAdFailedToLoad'`	Emits after trying to prepare a RewardAd when it could not be loaded
`Showed`	`'onRewardedVideoAdShowed'`	Emits when the AdReward video is visible to the user
`FailedToShow`	`'onRewardedVideoAdFailedToShow'`	Emits when the AdReward video is failed to show
`Dismissed`	`'onRewardedVideoAdDismissed'`	Emits when the AdReward video is not visible to the user anymore. Important: This has nothing to do with the reward it self. This event will emits in this two cases: 1. The user starts the video ad but close it before the reward emit. 2. The user start the video and see it until end, then gets the reward and after that the ad is closed.
`Rewarded`	`'onRewardedVideoAdReward'`	Emits when user get rewarded from AdReward