@capacitor-community/admob 8.1.0 → 8.2.0-beta.pr483.shac8cc94ca69ee

package/docs/migration.md

@@ -0,0 +1,144 @@
+# 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.6.0 (Swift Package Manager and CocoaPods). CocoaPods support is planned to be removed in the next major.
+
+## 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/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).

package/ios/Sources/AdMobPlugin/AdMobPlugin.swift

@@ -65,6 +65,10 @@ public class AdMobPlugin: CAPPlugin, CAPBridgedPlugin {
     private let adRewardInterstitialExecutor = AdRewardInterstitialExecutor()
     private let consentExecutor = ConsentExecutor()
 
+    public override func load() {
+        self.consentExecutor.plugin = self
+    }
+
     /**
      * Enable SKAdNetwork to track conversions
      * https://developers.google.com/admob/ios/ios14
@@ -75,7 +79,6 @@ public class AdMobPlugin: CAPPlugin, CAPBridgedPlugin {
         self.adRewardExecutor.plugin = self
         self.adRewardInterstitialExecutor.plugin = self
         self.adInterstitialExecutor.plugin = self
-        self.consentExecutor.plugin = self
         self.setRequestConfiguration(call)
 
         MobileAds.shared.start(completionHandler: nil)

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

@@ -38,7 +38,7 @@ import UIKit
                         let networkName = ad.responseInfo.loadedAdNetworkResponseInfo?.adNetworkClassName ?? ""
                         let impressionId = ad.responseInfo.responseIdentifier ?? ""
                         onPaidEvent(
-                            adValue.value.int64Value,
+                            adValue.value.multiplying(byPowerOf10: 6).int64Value,
                             adValue.currencyCode,
                             adValue.precision.rawValue,
                             networkName,

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

@@ -55,7 +55,7 @@ class BannerExecutor: NSObject, BannerViewDelegate {
                 let impressionId = self.bannerView.responseInfo?.responseIdentifier ?? ""
                 self.plugin?.notifyListeners(BannerAdPluginEvents.AdPaid.rawValue, data: [
                     "adUnitId": self.bannerView.adUnitID ?? "",
-                    "valueMicros": adValue.value.int64Value,
+                    "valueMicros": adValue.value.multiplying(byPowerOf10: 6).int64Value,
                     "currencyCode": adValue.currencyCode,
                     "precision": adValue.precision.rawValue,
                     "networkName": networkName,

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

@@ -16,10 +16,10 @@ class AdInterstitialExecutor: NSObject, FullScreenContentDelegate {
                 if let error = error {
                     NSLog("Interstitial ad failed to load with error: \(error.localizedDescription)")
                     self.plugin?.notifyListeners(InterstitialAdPluginEvents.FailedToLoad.rawValue, data: [
-                        "code": 0,
+                        "code": (error as NSError).code,
                         "message": error.localizedDescription
                     ])
-                    call.reject("Loading failed")
+                    call.reject(error.localizedDescription, String((error as NSError).code), error)
                     return
                 }
 
@@ -30,7 +30,7 @@ class AdInterstitialExecutor: NSObject, FullScreenContentDelegate {
                         let impressionId = ad.responseInfo.responseIdentifier ?? ""
                         self.plugin?.notifyListeners(InterstitialAdPluginEvents.AdImpression.rawValue, data: [
                             "adUnitId": adUnitID,
-                            "valueMicros": adValue.value.int64Value,
+                            "valueMicros": adValue.value.multiplying(byPowerOf10: 6).int64Value,
                             "currencyCode": adValue.currencyCode,
                             "precision": adValue.precision.rawValue,
                             "networkName": networkName,

package/ios/Sources/AdMobPlugin/Rewarded/AdRewardExecutor.swift

@@ -16,10 +16,10 @@ class AdRewardExecutor: NSObject, FullScreenContentDelegate {
                 if let error = error {
                     NSLog("Rewarded ad failed to load with error: \(error.localizedDescription)")
                     self.plugin?.notifyListeners(RewardAdPluginEvents.FailedToLoad.rawValue, data: [
-                        "code": 0,
+                        "code": (error as NSError).code,
                         "message": error.localizedDescription
                     ])
-                    call.reject("Loading failed")
+                    call.reject(error.localizedDescription, String((error as NSError).code), error)
                     return
                 }
 
@@ -50,7 +50,7 @@ class AdRewardExecutor: NSObject, FullScreenContentDelegate {
                     let impressionId = ad.responseInfo.responseIdentifier ?? ""
                     self.plugin?.notifyListeners(RewardAdPluginEvents.AdImpression.rawValue, data: [
                         "adUnitId": adUnitID,
-                        "valueMicros": adValue.value.int64Value,
+                        "valueMicros": adValue.value.multiplying(byPowerOf10: 6).int64Value,
                         "currencyCode": adValue.currencyCode,
                         "precision": adValue.precision.rawValue,
                         "networkName": networkName,
@@ -110,6 +110,10 @@ class AdRewardExecutor: NSObject, FullScreenContentDelegate {
         self.plugin?.notifyListeners(RewardAdPluginEvents.Showed.rawValue, data: [:])
     }
 
+    func adDidRecordClick(_ advertisement: FullScreenPresentingAd) {
+        self.plugin?.notifyListeners(RewardAdPluginEvents.adClicked.rawValue, data: [:])
+    }
+
     func adDidDismissFullScreenContent(_ ad: FullScreenPresentingAd) {
         removeCurrentlyShowingAd()
         NSLog("RewardFullScreenDelegate Ad did dismiss full screen content.")

package/ios/Sources/AdMobPlugin/Rewarded/RewardAdPluginEvents.swift

@@ -1,4 +1,5 @@
 public enum RewardAdPluginEvents: String {
+    case adClicked = "onRewardedVideoAdClicked"
     case Loaded = "onRewardedVideoAdLoaded"
     case FailedToLoad = "onRewardedVideoAdFailedToLoad"
     case Showed = "onRewardedVideoAdShowed"

package/ios/Sources/AdMobPlugin/RewardedInterstitial/AdRewardInterstitialExecutor.swift

@@ -16,10 +16,10 @@ class AdRewardInterstitialExecutor: NSObject, FullScreenContentDelegate {
                 if let error = error {
                     NSLog("Rewarded interstitial ad failed to load with error: \(error.localizedDescription)")
                     self.plugin?.notifyListeners(RewardInterstitialAdPluginEvents.FailedToLoad.rawValue, data: [
-                        "code": 0,
+                        "code": (error as NSError).code,
                         "message": error.localizedDescription
                     ])
-                    call.reject("Loading failed")
+                    call.reject(error.localizedDescription, String((error as NSError).code), error)
                     return
                 }
 
@@ -50,7 +50,7 @@ class AdRewardInterstitialExecutor: NSObject, FullScreenContentDelegate {
                     let impressionId = ad.responseInfo.responseIdentifier ?? ""
                     self.plugin?.notifyListeners(RewardInterstitialAdPluginEvents.AdImpression.rawValue, data: [
                         "adUnitId": adUnitID,
-                        "valueMicros": adValue.value.int64Value,
+                        "valueMicros": adValue.value.multiplying(byPowerOf10: 6).int64Value,
                         "currencyCode": adValue.currencyCode,
                         "precision": adValue.precision.rawValue,
                         "networkName": networkName,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@capacitor-community/admob",
   "private": false,
-  "version": "8.1.0",
+  "version": "8.2.0-beta.pr483.shac8cc94ca69ee",
   "description": "A native plugin for AdMob",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",
@@ -14,6 +14,7 @@
     "android/src/main/",
     "android/build.gradle",
     "dist/",
+    "docs/",
     "ios/Sources",
     "ios/Tests",
     "Package.swift",
@@ -28,6 +29,7 @@
   "bugs": {
     "url": "git@github.com:capacitor-community/admob.git/issues"
   },
+  "homepage": "https://docs.rdlabo.dev/projects/capacitor-admob",
   "scripts": {
     "verify": "npm run verify:ios && npm run verify:android && npm run verify:web",
     "verify:ios": "xcodebuild -scheme CapacitorCommunityAdmob -destination generic/platform=iOS",