@capacitor-community/admob 8.2.0 → 8.2.1-beta.pr490.shaf4a3cab095f4

package/docs/native-ads.md

@@ -0,0 +1,187 @@
+# Native Ads
+
+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 your feed 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`, the optional iOS `scrollElement`, and Android `androidScrollSnapshot`. 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 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.
+
+## Android scroll snapshots
+
+Set `androidScrollSnapshot: true` to display a cached image in the web feed while
+scrolling and restore the native ad when scrolling stops. The demo enables this
+option by default on Android.
+
+```ts
+const feed = await NativeAdFeed.create({
+  feedId: 'articles',
+  adId: 'YOUR_ANDROID_NATIVE_AD_UNIT_ID',
+  androidScrollSnapshot: true,
+});
+```
+
+Use `isTesting: true` during development to request Google's test ads. For production,
+provide your native ad unit ID in `adId` and omit `isTesting` or set it to `false`.
+Snapshots are available in either mode. The option is supported only on Android.
+
+WebView Native UI Engine manages snapshot capture and switching between the image
+and native view. Each ad slot has its own projection. Images are refreshed when the
+ad is reloaded or its layout changes; pausing, detaching, or destroying the feed
+hides or removes the corresponding projections.
+
+Video creatives and translucent backgrounds retain native tracking. If a snapshot
+is unavailable, not ready, or exceeds the supported dimensions, the native view
+continues tracking. Native SDK views handle ad interactions; snapshots do not
+forward clicks or synthesize impressions.

package/docs/rewarded.md

@@ -55,6 +55,19 @@ console.log(rewardItem);
 
 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

package/ios/Sources/AdMobPlugin/AdMobPlugin.swift

@@ -23,6 +23,11 @@ public class AdMobPlugin: CAPPlugin, CAPBridgedPlugin {
         CAPPluginMethod(name: "resumeBanner", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "hideBanner", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "removeBanner", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "startNativeAdFeed", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "destroyNativeAdFeed", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "loadNativeAd", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "updateNativeAdPlacements", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "removeNativeAd", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "prepareInterstitial", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "showInterstitial", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "prepareRewardVideoAd", returnType: CAPPluginReturnPromise),
@@ -64,25 +69,40 @@ public class AdMobPlugin: CAPPlugin, CAPBridgedPlugin {
     private let adRewardExecutor = AdRewardExecutor()
     private let adRewardInterstitialExecutor = AdRewardInterstitialExecutor()
     private let consentExecutor = ConsentExecutor()
+    private let nativeAdExecutor = NativeAdExecutor()
 
     public override func load() {
         self.consentExecutor.plugin = self
     }
 
-    /**
-     * Enable SKAdNetwork to track conversions
-     * https://developers.google.com/admob/ios/ios14
-     */
-    @objc func initialize(_ call: CAPPluginCall) {
-        self.bannerExecutor.plugin = self
-        self.adInterstitialExecutor.plugin = self
-        self.adRewardExecutor.plugin = self
-        self.adRewardInterstitialExecutor.plugin = self
-        self.adInterstitialExecutor.plugin = self
-        self.setRequestConfiguration(call)
+    /// Full-screen ads that currently have web media suspended.
+    private var webMediaSuspenders = Set<ObjectIdentifier>()
+
+    /// Pauses all web media while a full-screen ad is up, so WebKit releases its audio before the ad plays
+    /// and sets it up again afterwards, instead of leaving web audio silent until the app restarts.
+    func suspendWebMedia(for owner: AnyObject) {
+        Task { @MainActor [weak self] in
+            guard let self, self.webMediaSuspenders.insert(ObjectIdentifier(owner)).inserted,
+                self.webMediaSuspenders.count == 1
+            else { return }
+            self.setWebMediaPlaybackSuspended(true)
+        }
+    }
 
-        MobileAds.shared.start(completionHandler: nil)
-        call.resolve([:])
+    /// Only resumes once every ad that suspended has resumed, so a failed present (which can arrive
+    /// without a preceding adWillPresentFullScreenContent) can't release another ad's suspension.
+    func resumeWebMedia(for owner: AnyObject) {
+        Task { @MainActor [weak self] in
+            guard let self, self.webMediaSuspenders.remove(ObjectIdentifier(owner)) != nil,
+                self.webMediaSuspenders.isEmpty
+            else { return }
+            self.setWebMediaPlaybackSuspended(false)
+        }
+    }
+
+    @MainActor
+    func setWebMediaPlaybackSuspended(_ suspended: Bool) {
+        self.bridge?.webView?.setAllMediaPlaybackSuspended(suspended, completionHandler: nil)
     }
 
     /**
@@ -126,34 +146,12 @@ public class AdMobPlugin: CAPPlugin, CAPBridgedPlugin {
         }
     }
 
-    /**
-     *  AdMob: Banner
-     *  https://developers.google.com/ad-manager/mobile-ads-sdk/ios/banner?hl=ja
-     */
-    @objc func showBanner(_ call: CAPPluginCall) {
-        let adUnitID = getAdId(call, "ca-app-pub-3940256099942544/6300978111")
-        let request = self.GADRequestWithOption(call.getBool("npa") ?? false)
-
-        DispatchQueue.main.async {
-            self.bannerExecutor.showBanner(call, request, adUnitID)
-        }
-    }
-
-    @objc func hideBanner(_ call: CAPPluginCall) {
-        DispatchQueue.main.async {
-            self.bannerExecutor.hideBanner(call)
-        }
-    }
-
-    @objc func resumeBanner(_ call: CAPPluginCall) {
-        DispatchQueue.main.async {
-            self.bannerExecutor.resumeBanner(call)
-        }
-    }
-
-    @objc func removeBanner(_ call: CAPPluginCall) {
-        DispatchQueue.main.async {
-            self.bannerExecutor.removeBanner(call)
+    deinit {
+        let executor = nativeAdExecutor
+        if Thread.isMainThread {
+            executor.destroyAll()
+        } else {
+            DispatchQueue.main.async { executor.destroyAll() }
         }
     }
 
@@ -349,3 +347,67 @@ public class AdMobPlugin: CAPPlugin, CAPBridgedPlugin {
         return window?.rootViewController
     }
 }
+
+extension AdMobPlugin {
+    // MARK: SDK initialization
+
+    @objc func initialize(_ call: CAPPluginCall) {
+        bannerExecutor.plugin = self
+        adInterstitialExecutor.plugin = self
+        adRewardExecutor.plugin = self
+        adRewardInterstitialExecutor.plugin = self
+        adInterstitialExecutor.plugin = self
+        nativeAdExecutor.plugin = self
+        setRequestConfiguration(call)
+
+        MobileAds.shared.start(completionHandler: nil)
+        call.resolve([:])
+    }
+
+    // MARK: Banner ads
+
+    @objc func showBanner(_ call: CAPPluginCall) {
+        let adUnitID = getAdId(call, "ca-app-pub-3940256099942544/6300978111")
+        let request = GADRequestWithOption(call.getBool("npa") ?? false)
+        DispatchQueue.main.async {
+            self.bannerExecutor.showBanner(call, request, adUnitID)
+        }
+    }
+
+    @objc func hideBanner(_ call: CAPPluginCall) {
+        DispatchQueue.main.async { self.bannerExecutor.hideBanner(call) }
+    }
+
+    @objc func resumeBanner(_ call: CAPPluginCall) {
+        DispatchQueue.main.async { self.bannerExecutor.resumeBanner(call) }
+    }
+
+    @objc func removeBanner(_ call: CAPPluginCall) {
+        DispatchQueue.main.async { self.bannerExecutor.removeBanner(call) }
+    }
+
+    // MARK: Native ads research preview
+
+    @objc func startNativeAdFeed(_ call: CAPPluginCall) {
+        DispatchQueue.main.async { self.nativeAdExecutor.startFeed(call) }
+    }
+
+    @objc func destroyNativeAdFeed(_ call: CAPPluginCall) {
+        DispatchQueue.main.async { self.nativeAdExecutor.destroyFeed(call) }
+    }
+
+    @objc func loadNativeAd(_ call: CAPPluginCall) {
+        let request = GADRequestWithOption(call.getBool("npa") ?? false)
+        DispatchQueue.main.async {
+            self.nativeAdExecutor.load(call, request: request)
+        }
+    }
+
+    @objc func updateNativeAdPlacements(_ call: CAPPluginCall) {
+        DispatchQueue.main.async { self.nativeAdExecutor.updatePlacements(call) }
+    }
+
+    @objc func removeNativeAd(_ call: CAPPluginCall) {
+        DispatchQueue.main.async { self.nativeAdExecutor.remove(call) }
+    }
+}

package/ios/Sources/AdMobPlugin/AppOpen/AppOpenAdPluginEvents.swift

@@ -1,3 +1,5 @@
+// Preserve existing public Swift API names.
+// swiftlint:disable identifier_name
 public enum AppOpenAdPluginEvents: String {
     case Loaded = "appOpenAdLoaded"
     case FailedToLoad = "appOpenAdFailedToLoad"
@@ -6,3 +8,4 @@ public enum AppOpenAdPluginEvents: String {
     case FailedToShow = "appOpenAdFailedToShow"
     case AdImpression = "appOpenAdImpression"
 }
+// swiftlint:enable identifier_name

package/ios/Sources/AdMobPlugin/Banner/BannerAdPluginEvents.swift

@@ -1,3 +1,5 @@
+// Preserve existing public Swift API names.
+// swiftlint:disable identifier_name
 public enum BannerAdPluginEvents: String {
     case SizeChanged = "bannerAdSizeChanged"
     case Closed = "bannerAdClosed"
@@ -7,3 +9,4 @@ public enum BannerAdPluginEvents: String {
     case AdImpression = "bannerAdImpression"
     case AdPaid = "bannerAdPaid"
 }
+// swiftlint:enable identifier_name

package/ios/Sources/AdMobPlugin/Banner/BannerAdSizeEnum.swift

@@ -1,3 +1,5 @@
+// Preserve existing public Swift API names.
+// swiftlint:disable identifier_name
 public enum BannerAdSizeEnum: String {
     case BANNER = "BANNER"
     case FULL_BANNER = "FULL_BANNER"
@@ -8,3 +10,4 @@ public enum BannerAdSizeEnum: String {
     case ADAPTIVE_BANNER = "ADAPTIVE_BANNER"
     //    case FLUID = "FLUID"
 }
+// swiftlint:enable identifier_name

package/ios/Sources/AdMobPlugin/Banner/BannerExecutor.swift

@@ -6,7 +6,7 @@ class BannerExecutor: NSObject, BannerViewDelegate {
     weak var plugin: AdMobPlugin?
     var bannerView: BannerView!
     var adPosition: String = ""
-    var Margin: Int = 0
+    var margin: Int = 0
 
     func showBanner(_ call: CAPPluginCall, _ request: Request, _ adUnitID: String) {
         if let rootViewController = plugin?.getRootVC() {
@@ -112,11 +112,11 @@ class BannerExecutor: NSObject, BannerViewDelegate {
         call.resolve([:])
     }
 
-    private func addBannerViewToView(_ bannerView: BannerView, _ adPosition: String, _ Margin: Int) {
+    private func addBannerViewToView(_ bannerView: BannerView, _ adPosition: String, _ margin: Int) {
         removeBannerViewToView()
         bannerView.translatesAutoresizingMaskIntoConstraints = false
         bannerView.tag = 2743243288699 // rand
-        self.Margin = Margin
+        self.margin = margin
         self.adPosition = adPosition
     }
 
@@ -142,7 +142,7 @@ class BannerExecutor: NSObject, BannerViewDelegate {
                                     toItem: rootViewController.view.safeAreaLayoutGuide,
                                     attribute: self.adPosition == "TOP_CENTER" ? .top : .bottom,
                                     multiplier: 1,
-                                    constant: CGFloat(Int(self.Margin) * -1)),
+                                    constant: CGFloat(Int(self.margin) * -1)),
                  NSLayoutConstraint(item: bannerView,
                                     attribute: .centerX,
                                     relatedBy: .equal,

package/ios/Sources/AdMobPlugin/Helper/AuthorizationStatusEnum.swift

@@ -1,6 +1,9 @@
+// Preserve existing public Swift API names.
+// swiftlint:disable identifier_name
 public enum AuthorizationStatusEnum: String {
     case Authorized = "authorized"
     case Denied = "denied"
     case NotDetermined = "notDetermined"
     case Restricted = "restricted"
 }
+// swiftlint:enable identifier_name

package/ios/Sources/AdMobPlugin/Interstitial/AdInterstitialExecutor.swift

@@ -73,6 +73,7 @@ class AdInterstitialExecutor: NSObject, FullScreenContentDelegate {
     }
 
     func ad(_ ad: FullScreenPresentingAd, didFailToPresentFullScreenContentWithError error: Error) {
+        self.plugin?.resumeWebMedia(for: ad)
         removeCurrentlyShowingAd()
         NSLog("InterstitialFullScreenDelegate Ad failed to present full screen content with error \(error.localizedDescription).")
         self.plugin?.notifyListeners(InterstitialAdPluginEvents.FailedToShow.rawValue, data: [
@@ -82,11 +83,13 @@ class AdInterstitialExecutor: NSObject, FullScreenContentDelegate {
     }
 
     func adWillPresentFullScreenContent(_ ad: FullScreenPresentingAd) {
+        self.plugin?.suspendWebMedia(for: ad)
         NSLog("InterstitialFullScreenDelegate Ad did present full screen content.")
         self.plugin?.notifyListeners(InterstitialAdPluginEvents.Showed.rawValue, data: [:])
     }
 
     func adDidDismissFullScreenContent(_ ad: FullScreenPresentingAd) {
+        self.plugin?.resumeWebMedia(for: ad)
         removeCurrentlyShowingAd()
         NSLog("InterstitialFullScreenDelegate Ad did dismiss full screen content.")
         self.plugin?.notifyListeners(InterstitialAdPluginEvents.Dismissed.rawValue, data: [:])

package/ios/Sources/AdMobPlugin/Interstitial/InterstitialAdPluginEvents.swift

@@ -1,3 +1,5 @@
+// Preserve existing public Swift API names.
+// swiftlint:disable identifier_name
 public enum InterstitialAdPluginEvents: String {
     case Loaded = "interstitialAdLoaded"
     case FailedToLoad = "interstitialAdFailedToLoad"
@@ -6,3 +8,4 @@ public enum InterstitialAdPluginEvents: String {
     case Dismissed = "interstitialAdDismissed"
     case AdImpression = "interstitialAdImpression"
 }
+// swiftlint:enable identifier_name