@capacitor-community/admob 8.1.0 → 8.2.0

package/docs/rewarded.md

@@ -0,0 +1,135 @@
+# 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.
+
+### 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",
   "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",