@capacitor-community/admob 8.1.0 → 8.2.0

package/README.md

@@ -1,3 +1,4 @@
+<!-- rdlabo-docs-omit -->
 <p align="center"><br><img src="https://user-images.githubusercontent.com/236501/85893648-1c92e880-b7a8-11ea-926d-95355b8175c7.png" width="128" height="128" /></p>
 <h3 align="center">AdMob</h3>
 <p align="center"><strong><code>@capacitor-community/admob</code></strong></p>
@@ -5,6 +6,10 @@
   Capacitor community plugin for native AdMob.
 </p>
 
+<p align="center">
+  <strong><a href="https://docs.rdlabo.dev/projects/capacitor-admob">Read the full documentation</a></strong>
+</p>
+
 <p align="center">
   <img src="https://img.shields.io/maintenance/yes/2026?style=flat-square" />
   <a href="https://www.npmjs.com/package/@capacitor-community/admob"><img src="https://img.shields.io/npm/l/@capacitor-community/admob?style=flat-square" /></a>
@@ -15,10 +20,10 @@
 
 ## Maintainers
 
-| Maintainer          | GitHub                                           | Social                                          | Sponsoring Company                             |
-| ------------------- | ------------------------------------------------ | ----------------------------------------------- | ---------------------------------------------- |
-| Masahiko Sakakibara | [rdlabo](https://github.com/rdlabo)              | [@rdlabo](https://twitter.com/rdlabo)           | RELATION DESIGN LABO, GENERAL INC. ASSOCIATION |
-| Saninn Salas Diaz   | [Saninn Salas Diaz](https://github.com/distante) | [@SaninnSalas](https://twitter.com/SaninnSalas) |                                                |
+| Maintainer          | GitHub                                           | Social                                          | Website                                         |
+| ------------------- | ------------------------------------------------ | ----------------------------------------------- | ----------------------------------------------- |
+| Masahiko Sakakibara | [rdlabo](https://github.com/rdlabo)              | [@rdlabo](https://twitter.com/rdlabo)           | [rdlabo.dev](https://rdlabo.dev/)               |
+| Saninn Salas Diaz   | [Saninn Salas Diaz](https://github.com/distante) | [@SaninnSalas](https://twitter.com/SaninnSalas) | —                                               |
 
 Maintenance Status: Actively Maintained
 
@@ -41,51 +46,60 @@ Made with [contributors-img](https://contrib.rocks).
 | **iOS**     | ![](demo/screenshots/ios_banner.png) | ![](demo/screenshots/ios_interstitial.png) | ![](demo/screenshots/ios_reward.png) | ![](demo/screenshots/ios_open.png)  |
 | **Android** | ![](demo/screenshots/md_banner.png)  | ![](demo/screenshots/md_interstitial.png)  | ![](demo/screenshots/md_reward.png)  | ![](demo/screenshots/md_open.png)   |
 
+<!-- /rdlabo-docs-omit -->
+
+## Overview
+
+Capacitor community plugin for native AdMob. This plugin wraps the Google Mobile Ads SDK for iOS and Android so you can display banner, interstitial, rewarded, rewarded interstitial, and app open ads in Capacitor apps. It also covers Google User Messaging Platform (UMP) consent and App Tracking Transparency helpers on iOS.
+
 ## Installation
 
-If you use Capacitor 7:
+This plugin already ships Google Mobile Ads SDK. Install the package, then add your AdMob **application** ID in AndroidManifest / Info.plist. Google's Get started guides for [Android](https://developers.google.com/admob/android/quick-start) and [iOS](https://developers.google.com/admob/ios/quick-start) explain app IDs and SKAdNetwork identifiers (Apple's ad conversion IDs); do not add a second Mobile Ads dependency.
 
-```
-% npm install --save @capacitor-community/admob@7
-% npx cap update
-```
+This plugin targets `@capacitor-community/admob` **v8** and Capacitor 8.5 or later (within v8). It supports iOS 15 or later and Android API 24 or later.
 
-### Google Mobile Ads SDK compatibility
+```bash
+npm install @capacitor-community/admob
+npx cap sync
+```
 
-To preserve behavior for users of the current major version, this plugin continues to use Google Mobile Ads SDK APIs that are deprecated but still supported. Replacing those APIs can change banner sizing and age-restricted treatment behavior, so that migration is deferred until the next major release.
+If you still use Capacitor 7, install `@capacitor-community/admob@7`.
 
-Migration to the [GMA Next-Gen SDK for Android](https://developers.google.com/admob/android/next-gen) is also deferred until the next major release because it requires breaking changes to SDK initialization, ad requests, and mediation integration.
+### Google Mobile Ads SDK versions
 
-Android continues to use GMA SDK (Legacy) 25.4.x. On iOS, both Swift Package Manager and CocoaPods are fixed to GMA SDK 13.6.0 until CocoaPods support is removed in the next major release.
+This major version pins Google Mobile Ads SDK **25.4.x** on Android and **13.6.0** on iOS (Swift Package Manager and CocoaPods). Leave those versions unless you have a specific need. Google's [Next-Gen SDK for Android](https://developers.google.com/admob/android/next-gen) waits until the next plugin major. See [Migration](https://docs.rdlabo.dev/projects/capacitor-admob/docs/migration) for the policy behind the pins.
 
 ### Android configuration
 
-In file `android/app/src/main/AndroidManifest.xml`, add the following XML elements under `<manifest><application>` :
+In `android/app/src/main/AndroidManifest.xml`, add the following under `<application>`:
 
 ```xml
 <meta-data
- android:name="com.google.android.gms.ads.APPLICATION_ID"
- android:value="@string/admob_app_id"/>
+  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 :
+In `android/app/src/main/res/values/strings.xml`:
 
 ```xml
 <string name="admob_app_id">[APP_ID]</string>
 ```
 
-Don't forget to replace `[APP_ID]` by your AdMob application Id.
+Replace `[APP_ID]` with your AdMob **application** ID, not an ad unit ID.
 
 #### Variables
 
-This plugin will use the following project variables (defined in your app's `variables.gradle` file):
+You can leave these unset. Override them in your app's `variables.gradle` only when you need a specific artifact version:
 
-- `playServicesAdsVersion` version of `com.google.android.gms:play-services-ads` (default: `25.4.+`)
-- `androidxCoreKTXVersion`: version of `androidx.core:core-ktx` (default: `1.15.0`)
+| Variable                       | Artifact                                         | Default  |
+| ------------------------------ | ------------------------------------------------ | -------- |
+| `playServicesAdsVersion`       | `com.google.android.gms:play-services-ads`       | `25.4.+` |
+| `userMessagingPlatformVersion` | `com.google.android.ump:user-messaging-platform` | `4.0.0`  |
+| `androidxCoreKTXVersion`       | `androidx.core:core-ktx`                         | `1.15.0` |
 
 ### iOS configuration
 
-Add the following in the `ios/App/App/info.plist` file inside of the outermost `<dict>`:
+Add the following inside the outermost `<dict>` in `ios/App/App/Info.plist`:
 
 ```xml
 <key>GADIsAdManagerApp</key>
@@ -100,337 +114,90 @@ Add the following in the `ios/App/App/info.plist` file inside of the outermost `
   </dict>
 </array>
 <key>NSUserTrackingUsageDescription</key>
-<string>[Why you use NSUserTracking. ex: This identifier will be used to deliver personalized ads to you.]</string>
+<string>This identifier will be used to deliver personalized ads to you.</string>
 ```
 
-Don't forget to replace `[APP_ID]` by your AdMob application Id.
+Replace `[APP_ID]` with your AdMob application ID, and describe your actual tracking use in `NSUserTrackingUsageDescription`.
 
-## Example
-
-### Initialize AdMob
-
-```ts
-import { AdMob, AdmobConsentStatus } from '@capacitor-community/admob';
+The `SKAdNetworkItems` snippet includes Google's own identifier. Add the other IDs from Google's [iOS setup guide](https://developers.google.com/admob/ios/quick-start#update_your_infoplist).
 
-export async function initialize(): Promise<void> {
-  await AdMob.initialize();
+### Troubleshooting
 
-  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();
-  }
+If CocoaPods cannot resolve `Google-Mobile-Ads-SDK`:
 
-  const authorizationStatus = await AdMob.trackingAuthorizationStatus();
-  if (
-    authorizationStatus.status === 'authorized' &&
-    consentInfo.isConsentFormAvailable &&
-    consentInfo.status === AdmobConsentStatus.REQUIRED
-  ) {
-    await AdMob.showConsentForm();
-  }
-}
+```text
+[error] Error running update: Analyzing dependencies
+[!] CocoaPods could not find compatible versions for pod "Google-Mobile-Ads-SDK":
 ```
 
-Send an 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)
+Run `pod repo update` in `ios/`, then `npx cap sync ios` again.
 
-To use UMP, you must [create your GDPR messages](https://support.google.com/admob/answer/10113207?hl=en&ref_topic=10105230&sjid=6731900490614517032-AP).
+## First test banner
 
-You may need to [setup IDFA messages](https://support.google.com/admob/answer/10115027?hl=en), it will work along with GDPR messages and will show when users are not in EEA and UK.
+After installation and platform setup, initialize the SDK, request consent, and show a Google demo banner. Use the platform banner IDs from [Testing](https://docs.rdlabo.dev/projects/capacitor-admob/docs/testing)—do not create your own ad unit for this first check.
 
-Example of how to use UMP.
+Call `startAdMob` from a user action or after the UI is ready (for example a button or post-navigation hook), not only at module evaluation time.
 
 ```ts
-import { AdMob } from '@capacitor-community/admob';
+import { Capacitor } from '@capacitor/core';
+import { AdMob, AdmobConsentStatus, BannerAdOptions, BannerAdSize, BannerAdPosition } from '@capacitor-community/admob';
+
+const bannerAdId =
+  Capacitor.getPlatform() === 'ios'
+    ? 'ca-app-pub-3940256099942544/2934735716'
+    : 'ca-app-pub-3940256099942544/6300978111';
 
-private canShowAds: boolean | null = null;
+async function startAdMob() {
+  await AdMob.initialize();
 
-async showConsent() {
   let consentInfo = await AdMob.requestConsentInfo();
-  if (!consentInfo.canRequestAds) {
+  if (consentInfo.isConsentFormAvailable && consentInfo.status === AdmobConsentStatus.REQUIRED) {
     consentInfo = await AdMob.showConsentForm();
-    this.canShowAds = consentInfo.canRequestAds;
   }
-}
-```
-
-To let users manage their privacy options at any time, show the privacy options form.
-```ts
-import { AdMob } from '@capacitor-community/admob';
 
-showPrivacyOptionsForm() {
-    AdMob.showPrivacyOptionsForm();
-}
-```
-
-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).
-
-```ts
-import { AdMob, AdmobConsentDebugGeography } from '@capacitor-community/admob';
-
-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 App Open Ad
-
-```ts
-import {
-  AdMob,
-  AppOpenAdPluginEvents,
-  AppOpenAdOptions,
-  AdLoadInfo,
-} from '@capacitor-community/admob';
-
-export async function showAppOpenAd(): Promise<void> {
-  // listen to events
-  AdMob.addListener(AppOpenAdPluginEvents.Loaded, (info: AdLoadInfo) => {
-    console.log('App Open Ad loaded', info.adUnitId);
-  });
-  AdMob.addListener(AppOpenAdPluginEvents.FailedToLoad, (error) => {
-    console.log('Failed to load App Open Ad', error);
-  });
-  AdMob.addListener(AppOpenAdPluginEvents.Opened, () => {
-    console.log('App Open Ad open');
-  });
-  AdMob.addListener(AppOpenAdPluginEvents.Closed, () => {
-    console.log('App Open Ad close');
-  });
-  AdMob.addListener(AppOpenAdPluginEvents.FailedToShow, (error) => {
-    console.log('Failed to show App Open Ad', error);
-  });
-
-  const options: AppOpenAdOptions = {
-    adId: 'YOUR_AD_UNIT_ID',
-  };
-  const { adUnitId } = await AdMob.loadAppOpen(options);
-  const { value } = await AdMob.isAppOpenLoaded({ adId: adUnitId });
-  if (value) {
-    await AdMob.showAppOpen({ adId: adUnitId });
+  if (!consentInfo.canRequestAds) {
+    // Consent not ready — no banner is shown.
+    return;
   }
-}
-```
-### Show Banner
-
-```ts
-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,
+    adId: bannerAdId,
+    adSize: BannerAdSize.ADAPTIVE_BANNER,
     position: BannerAdPosition.BOTTOM_CENTER,
     margin: 0,
-    // isTesting: true
-    // npa: true
-  };
-  AdMob.showBanner(options);
-}
-```
-
-### Impression-level ad revenue
-
-Full-screen ad formats emit revenue data through their `AdImpression` event. Banners use the separate `AdPaid` event.
-
-```ts
-import {
-  AdMob,
-  AdMobRevenueData,
-  BannerAdPluginEvents,
-  InterstitialAdPluginEvents,
-} from '@capacitor-community/admob';
-
-AdMob.addListener(
-  InterstitialAdPluginEvents.AdImpression,
-  (data: AdMobRevenueData) => {
-    console.log(data);
-  },
-);
-
-AdMob.addListener(BannerAdPluginEvents.AdPaid, (data: AdMobRevenueData) => {
-  console.log(data);
-});
-```
-
-### Show Interstitial
-
-```ts
-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
-    // immersiveMode: true
-  };
-  await AdMob.prepareInterstitial(options);
-  await AdMob.showInterstitial();
-
-  // You can also prepare multiple interstitials and show a specific one by passing its adId:
-  await AdMob.prepareInterstitial({ adId: 'ca-app-pub-xxx/interstitial-1' });
-  await AdMob.prepareInterstitial({ adId: 'ca-app-pub-xxx/interstitial-2' });
-
-  // Show a specific prepared ad
-  await AdMob.showInterstitial({ adId: 'ca-app-pub-xxx/interstitial-1' });
-
-  // Or omit adId to show the most recently prepared one (default behavior)
-  await AdMob.showInterstitial();
-}
-```
-
-### Show RewardVideo
-
-```ts
-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
-    // immersiveMode: true
-    // ssv: {
-    //   userId: "A user ID to send to your SSV"
-    //   customData: JSON.stringify({ ...MyCustomData })
-    //}
   };
-  await AdMob.prepareRewardVideoAd(options);
-  const rewardItem = await AdMob.showRewardVideoAd();
-
-  // You can also prepare multiple reward ads and show a specific one by passing its adId:
-  await AdMob.prepareRewardVideoAd({ adId: 'ca-app-pub-xxx/reward-1' });
-  await AdMob.prepareRewardVideoAd({ adId: 'ca-app-pub-xxx/reward-2' });
-
-  // Show a specific prepared ad
-  const reward = await AdMob.showRewardVideoAd({ adId: 'ca-app-pub-xxx/reward-1' });
-
-  // Or omit adId to show the most recently prepared one (default behavior)
-  const reward2 = await AdMob.showRewardVideoAd();
+  await AdMob.showBanner(options);
 }
 ```
 
-### Show Rewarded Interstitial
+Expected result: when `canRequestAds` is true, a Google test banner appears at the bottom of the native screen. When `canRequestAds` is false, the function returns and no banner is shown. The banner sits above the WebView and can cover HTML—see [Banner Ads](https://docs.rdlabo.dev/projects/capacitor-admob/docs/banner) to inset your layout. Details: [Configuration](https://docs.rdlabo.dev/projects/capacitor-admob/docs/configuration), [Consent](https://docs.rdlabo.dev/projects/capacitor-admob/docs/consent), and [Testing](https://docs.rdlabo.dev/projects/capacitor-admob/docs/testing).
 
-```ts
-import { AdMob, RewardInterstitialAdOptions } from '@capacitor-community/admob';
+## Choose by advertising goal
 
-export async function rewardInterstitial(): Promise<void> {
-  const options: RewardInterstitialAdOptions = {
-    adId: 'YOUR ADID',
-  };
-  const { adUnitId } = await AdMob.prepareRewardInterstitialAd(options);
-  await AdMob.showRewardInterstitialAd({ adId: adUnitId });
-}
-```
+| Goal                                                              | Ad format                 | Guide                                      |
+| ----------------------------------------------------------------- | ------------------------- | ------------------------------------------ |
+| Keep an ad visible alongside app content                          | Banner                    | [Banner Ads](https://docs.rdlabo.dev/projects/capacitor-admob/docs/banner)             |
+| Show a full-screen ad at a natural break without granting a reward | Interstitial              | [Interstitial Ads](https://docs.rdlabo.dev/projects/capacitor-admob/docs/interstitial) |
+| Offer a dedicated rewarded experience                             | Rewarded                  | [Rewarded Ads](https://docs.rdlabo.dev/projects/capacitor-admob/docs/rewarded)         |
+| Offer a reward at a natural transition                            | Rewarded interstitial     | [Rewarded Ads](https://docs.rdlabo.dev/projects/capacitor-admob/docs/rewarded)         |
+| Monetize an app-open experience                                   | App Open                  | [App Open Ads](https://docs.rdlabo.dev/projects/capacitor-admob/docs/app-open)         |
 
-## Server-side Verification Notice
+## Documentation
 
-SSV callbacks are only fired on Production Adverts, therefore test Ads will not fire off your SSV callback.
+Start with [Installation](#installation) above, then [Configuration](https://docs.rdlabo.dev/projects/capacitor-admob/docs/configuration) and [Consent](https://docs.rdlabo.dev/projects/capacitor-admob/docs/consent). Run the first test banner, then use [Testing](https://docs.rdlabo.dev/projects/capacitor-admob/docs/testing) for demo units and devices. Pick an ad format from the table above. The same guides are also on the [documentation site](https://docs.rdlabo.dev/projects/capacitor-admob) (English and Japanese). If you opened this README on npm, use that site for the guides — the `docs/` files live in the GitHub repository. Method signatures are in the API section below.
 
-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:
-
-```ts
-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);
-    }
-  }
-  // ...
-});
-```
+- [Configuration](https://docs.rdlabo.dev/projects/capacitor-admob/docs/configuration) — `AdMob.initialize` and SDK options.
+- [Consent](https://docs.rdlabo.dev/projects/capacitor-admob/docs/consent) — privacy consent and iOS tracking authorization.
+- [Testing](https://docs.rdlabo.dev/projects/capacitor-admob/docs/testing) — demo ad units, test devices, and consent testing.
+- [Banner Ads](https://docs.rdlabo.dev/projects/capacitor-admob/docs/banner) — banner options, lifecycle, and events.
+- Full-screen ads:
+  - [Interstitial Ads](https://docs.rdlabo.dev/projects/capacitor-admob/docs/interstitial) — load, show, and multiple prepared ads.
+  - [Rewarded Ads](https://docs.rdlabo.dev/projects/capacitor-admob/docs/rewarded) — rewarded video, rewarded interstitial, and server-side verification.
+- [App Open Ads](https://docs.rdlabo.dev/projects/capacitor-admob/docs/app-open) — load and present on foreground transitions.
+- [Ad Events](https://docs.rdlabo.dev/projects/capacitor-admob/docs/events) — shared lifecycle events, errors, and revenue data.
+- [Migration Guide](https://docs.rdlabo.dev/projects/capacitor-admob/docs/migration) — historical notes when upgrading from older plugin versions.
 
+<!-- rdlabo-docs-omit -->
 ## Index
 
 <docgen-index>
@@ -474,6 +241,7 @@ AdMob.addListener(RewardAdPluginEvents.Rewarded, async () => {
 * [`addListener(InterstitialAdPluginEvents.AdImpression, ...)`](#addlistenerinterstitialadplugineventsadimpression-)
 * [`prepareRewardVideoAd(...)`](#preparerewardvideoad)
 * [`showRewardVideoAd(...)`](#showrewardvideoad)
+* [`addListener(RewardAdPluginEvents.adClicked, ...)`](#addlistenerrewardadplugineventsadclicked-)
 * [`addListener(RewardAdPluginEvents.FailedToLoad, ...)`](#addlistenerrewardadplugineventsfailedtoload-)
 * [`addListener(RewardAdPluginEvents.Loaded, ...)`](#addlistenerrewardadplugineventsloaded-)
 * [`addListener(RewardAdPluginEvents.Rewarded, ...)`](#addlistenerrewardadplugineventsrewarded-)
@@ -1001,6 +769,9 @@ prepareInterstitial(options: AdOptions) => Promise<AdLoadInfo>
 
 Loads an interstitial ad and returns the loaded ad unit ID.
 
+SDK load failures reject with the native error message and a string `code`.
+Codes are platform-specific; FailedToLoad events expose the same code as a number.
+
 | Param         | Type                                            | Description                        |
 | ------------- | ----------------------------------------------- | ---------------------------------- |
 | **`options`** | <code><a href="#adoptions">AdOptions</a></code> | <a href="#adoptions">AdOptions</a> |
@@ -1145,6 +916,9 @@ prepareRewardVideoAd(options: RewardAdOptions) => Promise<AdLoadInfo>
 
 Loads a rewarded ad and returns the loaded ad unit ID.
 
+SDK load failures reject with the native error message and a string `code`.
+Codes are platform-specific; FailedToLoad events expose the same code as a number.
+
 | Param         | Type                                                        | Description                                    |
 | ------------- | ----------------------------------------------------------- | ---------------------------------------------- |
 | **`options`** | <code><a href="#rewardadoptions">RewardAdOptions</a></code> | <a href="#rewardadoptions">RewardAdOptions</a> |
@@ -1175,6 +949,25 @@ Shows a loaded rewarded ad and resolves when the user earns the reward.
 --------------------
 
 
+### addListener(RewardAdPluginEvents.adClicked, ...)
+
+```typescript
+addListener(eventName: RewardAdPluginEvents.adClicked, listenerFunc: () => void) => Promise<PluginListenerHandle>
+```
+
+Listens for clicks recorded by the rewarded ad SDK, including after a reward is earned.
+A click does not indicate that the user earned a reward.
+
+| Param              | Type                                                                            |
+| ------------------ | ------------------------------------------------------------------------------- |
+| **`eventName`**    | <code><a href="#rewardadpluginevents">RewardAdPluginEvents.adClicked</a></code> |
+| **`listenerFunc`** | <code>() =&gt; void</code>                                                      |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+--------------------
+
+
 ### addListener(RewardAdPluginEvents.FailedToLoad, ...)
 
 ```typescript
@@ -1309,6 +1102,9 @@ prepareRewardInterstitialAd(options: RewardInterstitialAdOptions) => Promise<AdL
 
 Loads a rewarded interstitial ad and returns the loaded ad unit ID.
 
+SDK load failures reject with the native error message and a string `code`.
+Codes are platform-specific; FailedToLoad events expose the same code as a number.
+
 | Param         | Type                                                                                | Description                                                            |
 | ------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
 | **`options`** | <code><a href="#rewardinterstitialadoptions">RewardInterstitialAdOptions</a></code> | <a href="#rewardinterstitialadoptions">RewardInterstitialAdOptions</a> |
@@ -1799,6 +1595,7 @@ From T, pick a set of properties whose keys are in the union K
 
 | Members            | Value                                        | Description                                                                                                                                                        |
 | ------------------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **`adClicked`**    | <code>'onRewardedVideoAdClicked'</code>      | Emits when the SDK records a click on a rewarded ad.                                                                                                               |
 | **`Loaded`**       | <code>'onRewardedVideoAdLoaded'</code>       | Emits when a rewarded ad has loaded and is ready to show.                                                                                                          |
 | **`FailedToLoad`** | <code>'onRewardedVideoAdFailedToLoad'</code> | Emits when a rewarded ad fails to load.                                                                                                                            |
 | **`Showed`**       | <code>'onRewardedVideoAdShowed'</code>       | Emits when a rewarded ad is shown.                                                                                                                                 |
@@ -1822,15 +1619,23 @@ From T, pick a set of properties whose keys are in the union K
 
 </docgen-api>
 
-## TROUBLE SHOOTING
+## Prerelease channels
+
+An open, non-draft pull request can be published to the npm `beta` dist-tag after its `Validation` and `Package Candidate` workflows pass. A repository owner or maintainer must add a comment whose entire body is:
+
+```text
+/beta
+```
+
+The request authorizes only the pull request head SHA that existed when the comment was added. The workflow revalidates the owner or maintainer permission and head SHA immediately before publishing. Any new commit requires CI to pass again and a fresh owner or maintainer `/beta` comment. Fork pull requests are supported. Pull requests that change a release-gating workflow cannot be beta-published until those workflow changes land on `main`.
 
-### If you have error:
+Beta versions use `<base>-beta.pr<PR number>.sha<12-character SHA>`. The candidate is built in a read-only workflow without npm publishing credentials. The privileged release workflow publishes only the validated immutable package artifact with lifecycle scripts disabled. A notification failure cannot invalidate a successful npm publish.
 
-> [error] Error running update: Analyzing dependencies
-> [!] CocoaPods could not find compatible versions for pod "Google-Mobile-Ads-SDK":
+When a pull request is merged into `main`, it is automatically published to `beta` only after the required CI and `Package Candidate` succeed for that exact merge commit. Direct pushes to `main` do not publish a candidate.
 
-You should run `pod repo update` ;
+Only `npm run release` creates a release tag. Stable `vX.Y.Z` tags publish to npm `latest`; revision/prerelease tags publish to `next`. Neither `beta` nor `next` publishing changes the npm `latest` dist-tag.
 
 ## License
 
 Capacitor AdMob is [MIT licensed](./LICENSE).
+<!-- /rdlabo-docs-omit -->

package/android/build.gradle

@@ -37,7 +37,7 @@ android {
     buildTypes {
         release {
             minifyEnabled false
-            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
         }
     }
     lintOptions {

package/android/src/main/java/com/getcapacitor/community/admob/AdMob.java

@@ -103,8 +103,15 @@ public class AdMob extends Plugin {
                         public void onInitializationComplete(InitializationStatus initializationStatus) {}
                     }
                 );
-                bannerExecutor.initialize();
-                call.resolve();
+                // Resolve only once the banner parent actually exists, so a resolved
+                // initialize() means what callers already read it as. See #451.
+                bannerExecutor.awaitViewGroup((found) -> {
+                    if (found) {
+                        call.resolve();
+                    } else {
+                        call.reject("AdMob initialized, but the banner parent view never appeared");
+                    }
+                });
             } catch (Exception ex) {
                 call.reject(ex.getLocalizedMessage(), ex);
             }
@@ -185,7 +192,10 @@ public class AdMob extends Plugin {
 
     @PluginMethod
     public void showBanner(final PluginCall call) {
-        bannerExecutor.showBanner(call);
+        boolean systemBarsHandlesInsets = !"disable".equals(
+            getBridge().getConfig().getPluginConfiguration("SystemBars").getString("insetsHandling", "css")
+        );
+        bannerExecutor.showBanner(call, systemBarsHandlesInsets);
     }
 
     @PluginMethod