@capacitor-community/admob 8.1.0 → 8.2.0-beta.pr454.sha49386d40323a

package/docs/interstitial.md

@@ -0,0 +1,47 @@
+# Interstitial Ads
+
+Interstitial ads are full-screen ads that cover the host app. Show them at a natural transition, such as between activities or game levels. The user can tap through or close the ad and return to the app. Google's interstitial guides for [Android](https://developers.google.com/admob/android/interstitial) and [iOS](https://developers.google.com/admob/ios/interstitial) explain the format.
+
+Use an interstitial when the user should not receive an in-app reward. Call this after [initialize](https://docs.rdlabo.dev/projects/capacitor-admob/docs/configuration) and [consent](https://docs.rdlabo.dev/projects/capacitor-admob/docs/consent). Prepare the ad ahead of time, register listeners first, and show it only when it is ready.
+
+```ts
+import { AdLoadInfo, AdMob, AdMobRevenueData, AdOptions, InterstitialAdPluginEvents } from '@capacitor-community/admob';
+
+await AdMob.addListener(InterstitialAdPluginEvents.Loaded, (info: AdLoadInfo) => {
+  console.log('Interstitial loaded', info.adUnitId);
+});
+await AdMob.addListener(InterstitialAdPluginEvents.FailedToLoad, console.error);
+await AdMob.addListener(InterstitialAdPluginEvents.AdImpression, (data: AdMobRevenueData) => {
+  console.log(data);
+});
+
+const options: AdOptions = {
+  adId: 'YOUR_AD_UNIT_ID',
+  // isTesting: true,
+  // npa: true,
+  // immersiveMode: true,
+};
+const { adUnitId } = await AdMob.prepareInterstitial(options);
+await AdMob.showInterstitial({ adId: adUnitId });
+```
+
+<!-- !::prepareInterstitial:: -->
+
+<!-- !::showInterstitial:: -->
+
+<!-- !::AdOptions:: -->
+
+When no `adId` is passed to `showInterstitial()`, the most recently prepared ad is shown.
+
+## Prepare more than one ad
+
+```ts
+await AdMob.prepareInterstitial({ adId: 'ca-app-pub-xxx/interstitial-1' });
+await AdMob.prepareInterstitial({ adId: 'ca-app-pub-xxx/interstitial-2' });
+
+await AdMob.showInterstitial({ adId: 'ca-app-pub-xxx/interstitial-1' });
+```
+
+See [Testing](https://docs.rdlabo.dev/projects/capacitor-admob/docs/testing) for `isTesting`.
+
+Load, show, dismissal, and failure events are listed on [Ad Events](https://docs.rdlabo.dev/projects/capacitor-admob/docs/events).

package/docs/migration.md

@@ -0,0 +1,146 @@
+# Migration Guide
+
+## Changes in 8.2.0
+
+### Capacitor 8.5 or later is required
+
+Update `@capacitor/core`, `@capacitor/cli`, and the native platform packages you use (`@capacitor/android` / `@capacitor/ios`) to 8.5 or later within v8, then run `npx cap sync`.
+
+Older Capacitor versions can consume Android window insets before they reach a banner. Update Capacitor to use its current safe-area handling. Follow the [Capacitor 8.5 update guide](https://capacitorjs.com/docs/updating/8-5) for native project migration steps.
+
+### Android initialization can reject
+
+`AdMob.initialize()` now waits for the native banner parent view. If it does not appear within 5 seconds, initialization rejects; an unavailable activity/content view can fail immediately. This also applies to apps that only use full-screen ads. Previously, a missing child view could let initialization resolve and cause later banner requests to crash.
+
+Handle initialization errors without blocking app startup. Retry when the native view is available. See [Configuration](https://docs.rdlabo.dev/projects/capacitor-admob/docs/configuration) for an example.
+
+### iOS revenue values now use micros
+
+The `valueMicros` field now correctly reports millionths of a currency unit for banners, interstitials, rewarded ads, rewarded interstitials, and app-open ads. For example, a value of `0.0012` currency units previously produced `0`; it now produces `1200`. Android values and event names are unchanged.
+
+Divide `valueMicros` by `1_000_000` to obtain currency units on either platform. Review any iOS-specific workarounds in your analytics pipeline. Historical iOS values were truncated before conversion, so multiplying those stored values cannot recover the lost fractional revenue.
+
+### Consent before SDK initialization
+
+On iOS, `showConsentForm()` and `showPrivacyOptionsForm()` can now be called before `AdMob.initialize()`, matching Android. Request consent information, present a form if required, then initialize the Mobile Ads SDK and load ads only when `canRequestAds` is true. See [Consent](https://docs.rdlabo.dev/projects/capacitor-admob/docs/consent) for the complete sequence. Existing initialize-first integrations remain callable, but should adopt this order.
+
+### Ad load errors preserve native codes
+
+`prepareInterstitial()`, `prepareRewardVideoAd()`, and `prepareRewardInterstitialAd()` now reject SDK load failures with a string `code` and the native error message. Codes are platform-specific, not normalized across Android and iOS. `FailedToLoad` event codes remain numbers; on iOS they now contain the actual SDK code instead of a fixed `0`.
+
+Update error handlers that match the iOS message `Loading failed` or assume an event code of `0`. Use the platform's SDK error definitions when handling no-fill and other failures.
+
+### Rewarded ad click event
+
+`RewardAdPluginEvents.adClicked` is a new optional listener for rewarded ads on Android and iOS. Its event string is `onRewardedVideoAdClicked`. Clicks are separate from earned rewards; continue granting rewards only from the `Rewarded` event or the show result, once. See [Rewarded Ads](https://docs.rdlabo.dev/projects/capacitor-admob/docs/rewarded).
+
+### AGP 9 build compatibility
+
+The Android library now references `proguard-android-optimize.txt`, avoiding AGP 9's rejection of the older default file. This does not enable library minification or upgrade your project's AGP. Other AGP 9 migration steps still apply to the host app.
+
+The version-by-version steps under “Breaking changes from earlier versions” apply to releases before v8.
+
+## Google Mobile Ads SDK versions
+
+This major version keeps Google Mobile Ads SDK APIs that are deprecated but still supported. Replacing them can change banner sizing and age-restricted treatment, so that work waits for the next major.
+
+Google's [Next-Gen SDK for Android](https://developers.google.com/admob/android/next-gen) also waits for the next major: it changes SDK initialization, ad requests, and mediation.
+
+Pinned versions: Android 25.4.x, iOS 13.11.0 (Swift Package Manager and CocoaPods). CocoaPods support is planned to be removed in the next major.
+
+Android remains on 25.4.x because [SDK 25.5.0 raises the minimum Android API level](https://developers.google.com/admob/android/rel-notes). The iOS update from 13.6.0 to 13.11.0 keeps the plugin's existing platform and toolchain requirements; no public plugin API changes are required.
+
+## Breaking changes from earlier versions
+
+### 1.1.0
+
+- Prepare for iOS 14+
+- In file `ios/App/App/AppDelegate.swift` remove the following:
+
+```diff
+- import GoogleMobileAds
+
+  @UIApplicationMain
+  class AppDelegate: UIResponder, UIApplicationDelegate {
+
+    var window: UIWindow?
+
+    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
+-     // Override point for customization after application launch.
+-     GADMobileAds.sharedInstance().start(completionHandler: nil)
+```
+
+### 0.2.13
+
+- isTest: 'LIVE' | 'TESTING' => boolean
+
+### 0.2.12
+
+**app.component.ts**
+
+```ts
+import { Plugins } from '@capacitor/core';
+
+const { AdMob } = Plugins;
+
+@Component({
+  selector: 'app-root',
+  templateUrl: 'app.component.html',
+  styleUrls: ['app.component.scss'],
+})
+export class AppComponent {
+  constructor() {
+    // Initialize AdMob for your Application
+    +AdMob.initialize('[APP_ID]');
+    -AdMob.initialize();
+  }
+}
+```
+
+**admob.component.ts**
+
+```ts
+    import { Plugins } from '@capacitor/core';
+    import { AdOptions, AdSize, AdPosition } from '@rdlabo/capacitor-admob';
+
+    const { AdMob } = Plugins;
+
+    @Component({
+      selector: 'admob',
+      templateUrl: 'admob.component.html',
+      styleUrls: ['admob.component.scss']
+    })
+    export class AdMobComponent {
+
+        const options: AdOptions = {
+            adId: 'YOUR ADID',
+            adSize: AdSize.BANNER,
+            position: AdPosition.BOTTOM_CENTER,
+-           margin: '0',
++           margin: 0,
+        }
+
+        constructor(){
+            // Show Banner Ad
+            AdMob.showBanner(this.options)
+            .then(
+                (value) => {
+                    console.log(value);  // true
+                },
+                (error) => {
+                    console.error(error); // show error
+                }
+            );
+
+            // Subscibe Banner Event Listener
+            AdMob.addListener('onAdLoaded', (info: boolean) => {
+                 console.log("Banner Ad Loaded");
+            });
+
++           // Get Banner Size
++           AdMob.addListener('onAdSize', (info: boolean) => {
++                console.log(info);
++           });
+        }
+    }
+```

package/docs/native-ads.md

@@ -0,0 +1,161 @@
+# Native Ads (Preview)
+
+**Native Ads is a Preview feature.** You can use it for testing and in production. Its API may change in a minor release while in Preview.
+
+Native ads are rendered with Google Mobile Ads SDK views owned by this plugin. Your app reserves an HTML slot and supplies a stable key; it does not implement a `NativeAdView` in Kotlin or Swift and does not render ad assets in JavaScript.
+
+Native Ads is available on iOS and Android. Virtual scrolling is not yet supported. A native ad is placed above the WebView, so a pan beginning on the ad may not reach the WebView's scroll container. The implementation updates overlay coordinates as the WebView scrolls, but that cannot solve the initial gesture-routing problem.
+
+Browsers and PWAs are unsupported. `NativeAdFeed.create()` rejects instead of leaving an empty ad slot.
+
+## Create a feed
+
+Create one manager for each visible feed screen after initializing AdMob and obtaining consent.
+
+```ts
+import { NativeAdFeed, NativeAdPluginEvents, NativeAdTemplate } from '@capacitor-community/admob';
+
+const nativeAds = await NativeAdFeed.create({
+  feedId: 'home-feed',
+  template: NativeAdTemplate.Medium,
+  isTesting: true,
+  style: {
+    backgroundColor: '#ffffff',
+    cornerRadius: 12,
+    headlineColor: '#111827',
+    callToActionBackgroundColor: '#2563eb',
+  },
+});
+
+const paidHandle = await nativeAds.addListener(NativeAdPluginEvents.AdPaid, (event) => {
+  console.log(event.slotKey, event.valueMicros, event.currencyCode);
+});
+```
+
+Use the framework-independent element in ordinary or virtualized markup. `slot-key` must identify the logical ad item, not its array index and not the recycled DOM node.
+
+```html
+<capacitor-admob-native feed-id="home-feed" slot-key="sponsored-after-article-42"></capacitor-admob-native>
+```
+
+The element reserves `320px` for `Medium` and `120px` for `Small` only when author CSS does not provide a height. Author `display: none` and explicit height rules are respected. `Small` slots must be at least `120×120px`; `Medium` slots must be at least `144×300px`. Smaller slots are not loaded. These are lower bounds, not a guarantee that every creative and font size will fit. On Android, `Medium` stays hidden if its measured media area is smaller than `120×120dp`; increase the slot size to accommodate text, device font scaling, and pixel rounding. Do not animate or dynamically measure the slot height.
+
+`Small` has no video area. If the SDK returns a video ad for this template, the load fails with `NativeAdPluginEvents.FailedToLoad` (code `-1`); it is not displayed or automatically retried. Use `Medium` for ad units that serve video ads.
+
+If a framework does not accept custom elements, attach an ordinary element instead:
+
+```ts
+nativeAds.attach('sponsored-after-article-42', element);
+
+// Before the element is destroyed or reused for another logical item:
+nativeAds.detach(element);
+```
+
+Destroy the manager with its screen:
+
+```ts
+await paidHandle.remove();
+await nativeAds.destroy();
+```
+
+## Virtual-scroll integration experiments
+
+The stable-key lifecycle is designed for later validation with Angular CDK virtual scroll, React Virtuoso, and Vue Virtual Scroller. These integrations are examples for experiments, not a support claim:
+
+- Put the logical ad ID in `slot-key` (Angular binding, React prop/ref, or Vue `:slot-key`). Never use the rendered index.
+- Keep the ad row at a fixed height and include that height in the virtual scroller's item-size calculation.
+- When a library recycles a row, update the key or call `detach` before calling `attach` with the new key. The plugin hides the old generation before loading or showing the new one.
+- Use a single vertical scroll root. Nested scroll containers, horizontal virtual lists, sticky/transformed ancestors, and animated row heights are not in the initial support profile.
+
+For Angular, add `CUSTOM_ELEMENTS_SCHEMA` to the standalone component or NgModule that owns the feed, then bind attributes (not properties) inside the virtual row:
+
+```html
+<capacitor-admob-native feed-id="home-feed" [attr.slot-key]="item.stableAdKey"></capacitor-admob-native>
+```
+
+With React, `createElement` keeps custom dash-cased attributes type-safe without adding a framework dependency to the plugin:
+
+```tsx
+import { createElement } from 'react';
+
+const NativeAdRow = ({ slotKey }: { slotKey: string }) =>
+  createElement('capacitor-admob-native', {
+    'feed-id': 'home-feed',
+    'slot-key': slotKey,
+  });
+```
+
+For Vue, mark the tag as a custom element in the Vue compiler and bind the stable key:
+
+```ts
+// vite.config.ts
+vue({
+  template: {
+    compilerOptions: {
+      isCustomElement: (tag) => tag === 'capacitor-admob-native',
+    },
+  },
+});
+```
+
+```html
+<capacitor-admob-native feed-id="home-feed" :slot-key="item.stableAdKey" />
+```
+
+Use a normal HTML `overflow: auto` container or Ionic `ion-content`; Android requires no scroll-specific option. Ads follow the slot and its clipping bounds, but can lag behind fast scrolling. New ads load after scrolling settles.
+
+A feed keeps at most three native ads, including attached offscreen slots; additional visible slots wait for capacity. At most two feed managers may be active. Ads are not automatically refreshed, and failed loads are not silently retried. Call `reload(slotKey)` only at an explicit product-defined retry or refresh point.
+
+## Layout and overlay lifecycle
+
+Call `invalidateLayout()` after application-driven layout changes that can move a slot without scrolling, such as expanding an accordion. Slot size changes and captured image-load events are detected automatically.
+
+Native ads sit above WebView content and cannot infer that an Ionic modal, popover, menu, loading indicator, or route transition covers the slot. Hide the feed before presenting an overlay and resume it after dismissal:
+
+```ts
+await nativeAds.pause();
+await modal.present();
+await modal.onDidDismiss();
+nativeAds.resume();
+```
+
+Call `destroy()` when leaving a screen. Await `pause()` before presenting an overlay; it rejects if the native hide update fails. `resume()` waits for the viewport to settle before showing eligible placements again. `invalidateLayout()` likewise resolves only after the stale placement has been hidden.
+
+## API
+
+| Member                                         | Purpose                                                        |
+| ---------------------------------------------- | -------------------------------------------------------------- |
+| `NativeAdFeed.create(options)`                 | Starts a native feed session. Rejects outside iOS and Android. |
+| `feedId`                                       | Normalized feed identifier used by the custom element.         |
+| `addListener(event, listener)`                 | Adds a listener filtered to this feed session.                 |
+| `attach(slotKey, element)` / `detach(element)` | Advanced lifecycle for an ordinary element.                    |
+| `reload(slotKey)`                              | Explicitly removes and reloads one registered slot.            |
+| `pause(): Promise<void>` / `resume(): void`    | Hides placements during Web overlays or inactive page states.  |
+| `invalidateLayout(): Promise<void>`            | Hides and remeasures after an application-driven reflow.       |
+| `destroy()`                                    | Removes listeners and all native resources for the session.    |
+
+`NativeAdFeedOptions` contains `feedId`, `adId`, `template`, `style`, `isTesting`, `npa`, and the optional iOS `scrollElement`. Set `isTesting: true` to use Google's platform test ad unit. For production ads, set your platform-specific native ad unit ID in `adId` and omit `isTesting` or set it to `false`. `adId` is required unless `isTesting` is `true`. `feedId` and every `slotKey` must be non-empty and stable; reuse the same feed IDs across WebView reloads so stale native sessions can be replaced safely.
+
+## Rendering and policy boundary
+
+The `Small` and `Medium` templates, attribution, AdChoices, media, and clickable asset registration are owned by the plugin. The public style API intentionally exposes a limited set of cross-platform tokens instead of arbitrary native layouts or HTML asset rendering. This keeps Google SDK impression and click handling inside the native SDK.
+
+Style colors use CSS-style `#RRGGBB` or `#RRGGBBAA` values on both platforms. Dimensions use logical pixels; font sizes use points on iOS and `sp` on Android. Invalid colors fall back to the template defaults. Negative dimensions are clamped to zero; headline, body, and call-to-action fonts are clamped to `12–24`, `10–18`, and `12–18` respectively.
+
+Follow Google's native ad policies and implementation guidance for [Android](https://developers.google.com/admob/android/native/advanced) and [iOS](https://developers.google.com/admob/ios/native/advanced).
+
+## iOS scroll container
+
+For a single Ionic scroll container, pass its actual scroll element when creating the feed:
+
+```ts
+const feed = await NativeAdFeed.create({
+  feedId: 'articles',
+  isTesting: true,
+  scrollElement: await ionContent.getScrollElement(),
+});
+```
+
+On iOS, specifying `scrollElement` enables experimental native scroll tracking for that container. Layout changes still require remeasurement; call `invalidateLayout()` after application-driven changes. Clipping inside the scroll container and at its visible bounds is retained. `pause()` and `destroy()` stop tracking. Other platforms ignore this option and retain JavaScript coordinate updates.
+
+If the specified container cannot be identified unambiguously, the update fails and its ads stay hidden. Use one untransformed, unzoomed overflow scroll container; nested scrolling, document scrolling through this option, and virtual-scroll integrations are not supported. This does not change gesture routing for swipes that begin on an ad.

package/docs/rewarded.md

@@ -0,0 +1,148 @@
+# Rewarded Ads
+
+Rewarded ads let you give in-app items for interacting with video ads, playable ads, or surveys. Google's rewarded guides for [Android](https://developers.google.com/admob/android/rewarded) and [iOS](https://developers.google.com/admob/ios/rewarded) explain the format.
+
+Treat rewarded ads as a reward flow, not as another non-rewarded interstitial. Call this after [initialize](https://docs.rdlabo.dev/projects/capacitor-admob/docs/configuration) and [consent](https://docs.rdlabo.dev/projects/capacitor-admob/docs/consent). Grant the reward only from the returned result or the `Rewarded` event, not from `Dismissed`.
+
+## Rewarded video
+
+Use a rewarded ad for a dedicated reward flow.
+
+```ts
+import {
+  AdLoadInfo,
+  AdMob,
+  AdMobRevenueData,
+  AdMobRewardItem,
+  RewardAdOptions,
+  RewardAdPluginEvents,
+} from '@capacitor-community/admob';
+
+await AdMob.addListener(RewardAdPluginEvents.Loaded, (info: AdLoadInfo) => {
+  console.log('Rewarded ad loaded', info.adUnitId);
+});
+await AdMob.addListener(RewardAdPluginEvents.FailedToLoad, console.error);
+await AdMob.addListener(RewardAdPluginEvents.Rewarded, (reward: AdMobRewardItem) => {
+  console.log('Reward earned', reward.amount, reward.type);
+});
+await AdMob.addListener(RewardAdPluginEvents.AdImpression, (data: AdMobRevenueData) => {
+  console.log(data);
+});
+
+const options: RewardAdOptions = {
+  adId: 'YOUR_AD_UNIT_ID',
+  // isTesting: true,
+  // npa: true,
+  // immersiveMode: true,
+  // ssv: {
+  //   userId: 'USER_ID',
+  //   customData: JSON.stringify({ placement: 'bonus' }),
+  // },
+};
+await AdMob.prepareRewardVideoAd(options);
+const rewardItem = await AdMob.showRewardVideoAd();
+// Grant the reward once, using this result or the Rewarded event — not both.
+console.log(rewardItem);
+```
+
+<!-- !::prepareRewardVideoAd:: -->
+
+<!-- !::showRewardVideoAd:: -->
+
+<!-- !::RewardAdOptions:: -->
+
+<!-- !::AdMobRewardItem:: -->
+
+When no `adId` is passed to `showRewardVideoAd()`, the most recently prepared ad is shown.
+
+### Click events (since 8.2.0)
+
+Register `adClicked` before showing a rewarded ad. This forwards clicks recorded by the SDK, including after a reward is earned while the ad remains displayed. It does not indicate that a reward was earned and does not apply to rewarded interstitials.
+
+```ts
+const clickListener = await AdMob.addListener(RewardAdPluginEvents.adClicked, () => {
+  console.log('Rewarded ad clicked');
+});
+
+// When the owning screen is destroyed:
+await clickListener.remove();
+```
+
+### Prepare more than one ad
+
+```ts
+await AdMob.prepareRewardVideoAd({ adId: 'ca-app-pub-xxx/reward-1' });
+await AdMob.prepareRewardVideoAd({ adId: 'ca-app-pub-xxx/reward-2' });
+
+const reward = await AdMob.showRewardVideoAd({ adId: 'ca-app-pub-xxx/reward-1' });
+```
+
+## Rewarded interstitial
+
+Rewarded interstitial ads are incentivized full-screen ads that appear during natural app transitions. Unlike rewarded video, the user does not opt in first. Google's rewarded interstitial guides for [Android](https://developers.google.com/admob/android/rewarded-interstitial) and [iOS](https://developers.google.com/admob/ios/rewarded-interstitial) explain the format.
+
+Use a rewarded interstitial when the rewarded experience belongs at a natural transition in the app.
+
+```ts
+import {
+  AdMob,
+  AdMobRewardInterstitialItem,
+  RewardInterstitialAdOptions,
+  RewardInterstitialAdPluginEvents,
+} from '@capacitor-community/admob';
+
+await AdMob.addListener(RewardInterstitialAdPluginEvents.FailedToLoad, console.error);
+
+const options: RewardInterstitialAdOptions = {
+  adId: 'YOUR_AD_UNIT_ID',
+};
+const { adUnitId } = await AdMob.prepareRewardInterstitialAd(options);
+const rewardItem: AdMobRewardInterstitialItem = await AdMob.showRewardInterstitialAd({
+  adId: adUnitId,
+});
+console.log(rewardItem);
+```
+
+<!-- !::prepareRewardInterstitialAd:: -->
+
+<!-- !::showRewardInterstitialAd:: -->
+
+<!-- !::RewardInterstitialAdOptions:: -->
+
+<!-- !::AdMobRewardInterstitialItem:: -->
+
+See [Testing](https://docs.rdlabo.dev/projects/capacitor-admob/docs/testing) for `isTesting`.
+
+## Server-side verification
+
+Server-side verification (SSV) lets your backend confirm that a reward was earned. See Google's [SSV documentation](https://support.google.com/admob/answer/9603226). Callbacks fire only for production ads; test ads do not invoke your SSV endpoint.
+
+For local validation of the `ssv` payload, you can send a mock request after `RewardAdPluginEvents.Rewarded`. Replace `ENVIRONMENT_IS_DEVELOPMENT` with your own development flag:
+
+```ts
+const userId = 'USER_ID';
+const customData = JSON.stringify({ placement: 'bonus' });
+
+await AdMob.addListener(RewardAdPluginEvents.Rewarded, async () => {
+  if (!ENVIRONMENT_IS_DEVELOPMENT) {
+    return;
+  }
+  try {
+    const params = new URLSearchParams({
+      ad_network: 'TEST',
+      ad_unit: 'TEST',
+      custom_data: customData,
+      reward_amount: 'TEST',
+      reward_item: 'TEST',
+      timestamp: 'TEST',
+      transaction_id: 'TEST',
+      user_id: userId,
+      signature: 'TEST',
+      key_id: 'TEST',
+    });
+    await fetch(`https://your-staging-ssv-endpoint?${params.toString()}`);
+  } catch (err) {
+    console.error(err);
+  }
+});
+```

package/docs/testing.md

@@ -0,0 +1,67 @@
+# Testing
+
+Use test ads during development so you can click ads without charging advertisers or flagging the account for invalid traffic. Google's test ads guides for [Android](https://developers.google.com/admob/android/test-ads) and [iOS](https://developers.google.com/admob/ios/test-ads) explain demo ad units and test devices.
+
+This plugin can request those demo units or register a device through `initialize`.
+
+## Demo ad units
+
+Google provides [demo ad units](https://developers.google.com/admob/android/test-ads#demo_ad_units) that always return test ads. Prefer these during development. This plugin supports native iOS and Android only—use the matching platform ID.
+
+Banner demo units used by this plugin and its demo:
+
+| Platform | Banner `adId` |
+| --- | --- |
+| Android | `ca-app-pub-3940256099942544/6300978111` |
+| iOS | `ca-app-pub-3940256099942544/2934735716` |
+
+Other format demo IDs are listed in Google's test-ads guides linked above. You can also set `isTesting: true` on banner, interstitial, rewarded, and rewarded interstitial requests. App Open ads have no `isTesting` option; pass a demo ad unit as `adId`.
+
+## Test devices
+
+To request production-like ads on a physical device without generating invalid traffic, register the device with `AdMob.initialize()`:
+
+```ts
+await AdMob.initialize({
+  testingDevices: ['YOUR_TEST_DEVICE_ID'],
+  initializeForTesting: true,
+});
+```
+
+<!-- !::initialize:: -->
+
+<!-- !::AdMobInitializationOptions:: -->
+
+Find the device ID in the native logs after the first ad request:
+
+- Android: Logcat, typically on the `Ads` tag (`Use RequestConfiguration.Builder.setTestDeviceIds(...)`).
+- iOS: Xcode console (`To get test ads on this device, set:`).
+
+See Google's [enable test devices](https://developers.google.com/admob/android/test-ads#enable_test_devices) guide.
+
+## Consent debug geography
+
+On a real device, set `debugGeography` and include the device ID in `testDeviceIdentifiers`. `EEA` makes the form behave as if the device were in the European Economic Area, so you can test GDPR messaging. Use this only on registered test devices.
+
+```ts
+import { AdMob, AdmobConsentDebugGeography } from '@capacitor-community/admob';
+
+const consentInfo = await AdMob.requestConsentInfo({
+  debugGeography: AdmobConsentDebugGeography.EEA,
+  testDeviceIdentifiers: ['YOUR_TEST_DEVICE_ID'],
+});
+```
+
+<!-- !::requestConsentInfo:: -->
+
+<!-- !::AdmobConsentRequestOptions:: -->
+
+<!-- !::AdmobConsentDebugGeography:: -->
+
+If you decline consent in the test form (Manage → Confirm Choices), ads may not load. That is expected in a test environment and does not predict production behavior after a user consents.
+
+`resetConsentInfo()` is for tests only. See [Consent](https://docs.rdlabo.dev/projects/capacitor-admob/docs/consent).
+
+## Server-side verification
+
+Server-side verification (SSV) callbacks fire only for production ads. Test ads will not hit your SSV endpoint. For a mock request example, see [Rewarded Ads](https://docs.rdlabo.dev/projects/capacitor-admob/docs/rewarded).