@javascriptcommon/react-native-google-mobile-ads 16.3.3

package/docs/mediation.mdx

@@ -0,0 +1,323 @@
+# Mediation
+
+AdMob Mediation is a feature lets you serve ads to your apps from multiple sources, including the AdMob Network and third-party ad sources, in one place. 
+AdMob Mediation helps maximize your fill rate and increase your monetization by sending ad requests to multiple networks to verify you find the best 
+available network to serve ads.
+
+This guide walks you through configuring mediation using the `react-native-google-mobile-ads` library.
+
+## Configure mediation in the AdMob UI
+
+To configure mediation in the AdMob UI, complete the following steps:
+
+1. Choose an ad source from the network details table ([Android](https://developers.google.com/admob/android/choose-networks#network_details) | [iOS](https://developers.google.com/admob/ios/choose-networks#network_details)).
+2. Follow steps 1-2 of that ad source's integration guide.
+
+## Install mediation adapters
+
+For the Google Mobile Ads SDK to communicate with third-party ad networks, you need to include a mediation adapter for each network in your app. Each
+adapter must be integrated in the Android and iOS layer of your application. 
+
+To choose the adapters you want to install, see Integrate open source and versioned adapters
+([Android](https://developers.google.com/admob/android/choose-networks#integrate_open-source_and_versioned_adapters) | [iOS](https://developers.google.com/admob/ios/choose-networks#integrate_open-source_and_versioned_adapters)).
+
+<Tabs groupId="framework" values={[{label: 'React Native', value: 'bare'}, {label: 'Expo', value: 'expo'}]}>
+<TabItem value="bare">
+
+Android
+- Add the adapter's dependency to your app-level `android/app/build.gradle` file.
+
+iOS
+- Add the adapter's pod to your `ios/Podfile`.
+
+</TabItem>
+<TabItem value="expo">
+
+Add native dependencies using the [`expo-build-properties`](https://docs.expo.dev/versions/latest/sdk/build-properties) plugin.
+
+Install the plugin if you haven't already:
+
+```bash
+npx expo install expo-build-properties
+```
+
+Add the plugin to your `app.json` or `app.config.js` file, specifying the Android dependency or iOS pod for the adapter.
+
+```json
+// app.json
+{
+  "expo": {
+    "plugins": [
+      [
+        "expo-build-properties",
+        {
+          "android": {
+            "dependencies": [
+              // Example: Add the AppLovin mediation adapter for Android. Replace {X.Y.Z.A} with the specific adapter version you are integrating.
+              "com.google.ads.mediation:applovin:{X.Y.Z.A}"
+            ]
+          },
+          "ios": {
+            "pods": [
+              {
+                // Example: Add the AppLovin mediation adapter for iOS.
+                "name": "GoogleMobileAdsMediationAppLovin"
+              }
+            ]
+          }
+        }
+      ]
+    ]
+  }
+}
+```
+
+Rebuild your development client to include the new native dependencies:
+
+```bash
+npx expo prebuild --clean
+npx expo run:android
+npx expo run:ios
+```
+
+</TabItem>
+</Tabs>
+
+## Verify your setup with ad inspector
+
+To open the ad inspector from your React Native application, see [Ad inspector](https://docs.page/invertase/react-native-google-mobile-ads/ad-inspector) in the
+`react-native-google-mobile-ads` documentation.
+
+## Call Android / iOS code from React Native
+
+A third-party mediation adapter might have specific Android or iOS APIs that aren't exposed to your Reach Native code. In these cases, you can create a custom "bridge" to expose that native functionality.
+
+<Tabs groupId="framework" values={[{label: 'React Native', value: 'bare'}, {label: 'Expo', value: 'expo'}]}>
+<TabItem value="bare">
+
+This involves writing native code in both the Android and iOS layer.
+
+**Android**
+
+Create a `Module` class to contain your native logic and a `Package` class to register that module with your application.
+
+1. Create the native module. This class contains the methods you want to call from JavaScript.
+
+Example file: `android/app/src/main/java/com/your-app-name/`
+
+The following example creates a **Module** class to use with the Google Mobile Ads mediation adapter for AppLovin:
+
+```
+package com.your-app-name
+
+import android.util.Log
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+// Import the necessary third-party SDKs.
+import com.applovin.sdk.AppLovinPrivacySettings
+
+class GoogleMobileAdsMediationAppLovinModule(reactContext: ReactApplicationContext) : ReactContextBaseJavaModule(reactContext) {
+
+  // The React layer interfaces with the value of this API. 
+  override fun getName() = "GoogleMobileAdsMediationAppLovin"
+
+  // This exposes the method to the React layer.
+  @ReactMethod
+  fun setHasUserConsent(hasUserConsent: Boolean) {
+    AppLovinPrivacySettings.setHasUserConsent(hasUserConsent)
+  }
+}
+```
+
+2. Create the package
+
+    This class registers your module so React Native can find it.
+
+Example file: `android/app/src/main/java/com/your-app-name/`
+
+```
+package com.your-app-name
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+import java.util.Collections
+
+class GoogleMobileAdsMediationAppLovinPackage : ReactPackage {
+  override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> {
+    return listOf(GoogleMobileAdsMediationAppLovinModule(reactContext))
+  }
+
+  override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> {
+    return Collections.emptyList()
+  }
+}
+```
+
+3. Register the package
+
+Add your new package in your `MainApplication` file:
+
+```
+override fun getPackages(): List<ReactPackage> =
+  PackageList(this).packages.apply {
+    // Add your custom package here.
+    add(GoogleMobileAdsMediationAppLovinPackage())
+}
+```
+
+**iOS**
+
+Create a header (`.h`) and an implementation (`.m`) file. The following example creates an `GoogleMobileAdsMediationAppLovin` class:
+
+Example file: `ios/GoogleMobileAdsMediationAppLovin.h`
+
+```
+#import <React/RCTBridgeModule.h>
+
+@interface GoogleMobileAdsMediationAppLovin : NSObject <RCTBridgeModule>
+@end
+```
+
+Example file: `ios/GoogleMobileAdsMediationAppLovin.m`
+
+```
+#import "GoogleMobileAdsMediationAppLovin.h"
+#import <Foundation/Foundation.h>
+// Import the necessary third-party SDKs.
+#import <AppLovinSDK/AppLovinSDK.h>
+
+@implementation GoogleMobileAdsMediationAppLovin
+
+// The React layer interfaces with the class name, e.g. GoogleMobileAdsMediationAppLovin, by default. 
+RCT_EXPORT_MODULE();
+
+// This exports the method to the React layer.
+RCT_EXPORT_METHOD(setHasUserConsent:(BOOL)hasUserConsent)
+{
+  [ALPrivacySettings setHasUserConsent:hasUserConsent];
+}
+
+@end
+```
+
+**Import native modules**
+
+In the JavaScript file where you want to call the native method, import `NativeModules` from the `react-native` library:
+
+```
+import { NativeModules } from 'react-native'
+```
+
+You can then access your module directly from the `NativeModules` object. The name you use here must exactly match the name
+exposed by your native code.
+
+The following example uses the `GoogleMobileAdsMediationAppLovin` sample class:
+
+```
+const { GoogleMobileAdsMediationAppLovin } = NativeModules
+```
+
+Once you have the module object, you can work with your object just as you would in Javascript.
+
+```
+GoogleMobileAdsMediationAppLovin.setHasUserConsent(true)
+```
+
+</TabItem>
+<TabItem value="expo">
+
+1. **Create an [Expo module](https://docs.expo.dev/modules/get-started/)** with the `create-expo-module` tool.
+
+Run the following command from your project's root directory:
+
+```
+npx create-expo-module --local
+```
+
+When prompted, give your module a name. This will scaffold a new module in a modules/ directory at your project root. 
+
+2. **Add your native Android and iOS code**. The following example creates a module to use with the
+Google Mobile Ads mediation adapter for AppLovin:
+
+Android
+
+Open the generated Kotlin file for your module and add your custom method. The module and package are already set up for you.
+
+File: `modules/google-mobile-ads-mediation-applovin/android/src/main/java/.../GoogleMobileAdsMediationApplovinModule.kt`
+
+```
+// ... existing imports
+import com.applovin.sdk.AppLovinPrivacySettings
+
+class GoogleMobileAdsMediationApplovinModule : Module() {
+  override fun definition() = ModuleDefinition {
+    // ... existing definition
+
+    // Add your custom method here.
+    Function("setHasUserConsent") { hasUserConsent: Boolean ->
+      AppLovinPrivacySettings.setHasUserConsent(hasUserConsent)
+    }
+  }
+}
+```
+
+Then, add the dependency in your module's `build.gradle` file.
+
+File: `modules/google-mobile-ads-mediation-applovin/android/build.gradle`
+
+```
+// Groovy
+
+dependencies {
+  // Add the third-party SDK dependency. Replace {X.Y.Z.A} with the specific adapter version you are integrating.
+  implementation 'com.google.ads.mediation:applovin:{X.Y.Z.A}'
+}
+```
+
+iOS
+
+Open the generated Swift file for your module and add your custom method.
+
+File: `modules/google-mobile-ads-mediation-applovin/ios/GoogleMobileAdsMediationApplovinModule.swift`
+
+```
+// ... existing imports
+import AppLovinSDK
+
+public class GoogleMobileAdsMediationApplovinModule: Module {
+  public func definition() -> ModuleDefinition {
+    // ... existing definition
+
+    // Add your custom method here
+    Function("setHasUserConsent") { (hasUserConsent: Bool) in
+      ALPrivacySettings.setHasUserConsent(hasUserConsent)
+    }
+  }
+}
+```
+
+Next, add the dependency in your module's `.podspec` file.
+
+File: `modules/google-mobile-ads-mediation-applovin/google-mobile-ads-mediation-applovin.podspec`
+
+```
+# Add the third-party pod dependency.
+s.dependency 'GoogleMobileAdsMediationAppLovin'
+```
+
+3. **Install and rebuild**. After creating the module and adding the code, install it in your project and rebuild your development client.
+
+4. **Call the code from JavaScript**. You can now import and use the module directly in your code.
+
+```
+import { setHasUserConsent } from 'google-mobile-ads-mediation-applovin'
+
+// Call your custom native method.
+setHasUserConsent(true)
+```
+
+</TabItem>
+</Tabs>

package/docs/migrating-to-v15.mdx

@@ -0,0 +1,7 @@
+# Migrating to v15
+
+## Important Notice (Android Only)
+
+If you're upgrading to v15, please note that it requires Kotlin 2.0.0. Ensure your project is updated accordingly to prevent build issues.
+
+Open your `android/build.gradle` file and update the Kotlin version to "2.0.0".

package/docs/migrating-to-v5.mdx

@@ -0,0 +1,63 @@
+# Migrating to v5
+
+## AdsConsent
+
+Google replaced their Consent SDK with the User Messaging Platform (UMP) SDK, which supports the latest IAB standards and Apple's App Tracking Transparency requirements.
+
+Please refer to the following links for more information:
+
+- [User Messaging Platform](https://developers.google.com/admob/ump/ios/quick-start)
+- [EU User Consent Policy](https://www.google.com/about/company/user-consent-policy/)
+- [IAB Europe Transparency](https://iabeurope.eu/iab-europe-transparency-consent-framework-policies/)
+- [App Tracking Transparency](https://developer.apple.com/documentation/apptrackingtransparency)
+
+Previously it was possible to request the ad providers and to update the consent status. This is no longer the case.
+Also, while the old Consent SDK provided information about user preferences, the new `AdsConsentStatus` only tells you if you should show the modal to a user or not.
+
+- `requestInfoUpdate` does now accept an optional `AdsConsentInfoOptions` object instead of expecting `publisherIds` and returns a changed `AdsConsentInfo` interface
+- `showForm` does not expect any parameters any longer and now only returns the changed `AdsConsentStatus` as part of it's `AdsConsentFormResult` interface
+- `getAdProviders`, `getStatus` and `setStatus` methods were removed without replacements
+- `addTestDevices`, `setDebugGeography` and `setTagForUnderAgeOfConsent` methods were removed, but their functionality is available via `AdsConsentInfoOptions`
+- the `user_tracking_usage_description` key is needed in your project's `app.json` if you want to handle Apple's App Tracking Transparency
+- newly added `getUserChoices` can be used to inspect some of the consent choices
+
+```diff
+ {
+   "react-native-google-mobile-ads": {
+     "android_app_id": "ca-app-pub-xxxxxxxx~xxxxxxxx",
+     "ios_app_id": "ca-app-pub-xxxxxxxx~xxxxxxxx",
++    "user_tracking_usage_description": "This identifier will be used to deliver personalized ads to you."
+   }
+ }
+```
+
+```diff
+ import { AdsConsent, AdsConsentStatus } from 'react-native-google-mobile-ads';
+
+-const consentInfo = await AdsConsent.requestInfoUpdate(['pub-6189033257628123']);
++const consentInfo = await AdsConsent.requestInfoUpdate();
+
+ if (
+-  consentInfo.isRequestLocationInEeaOrUnknown &&
++  consentInfo.isConsentFormAvailable &&
+-  consentInfo.status === AdsConsentStatus.UNKNOWN
++  consentInfo.status === AdsConsentStatus.REQUIRED
+ ) {
+-  const formResult = await AdsConsent.showForm({
+-    privacyPolicy: 'https://invertase.io/privacy-policy',
+-    withPersonalizedAds: true,
+-    withNonPersonalizedAds: true,
+-    withAdFree: true,
+-  });
++  const formResult = await AdsConsent.showForm()
++
++  const { storeAndAccessInformationOnDevice } = await AdsConsent.getUserChoices();
++
++  if (storeAndAccessInformationOnDevice === false) {
++    /**
++     * The user declined consent for purpose 1,
++     * the Google Mobile Ads SDK won't serve ads.
++     */
++  }
+ }
+```

package/docs/migrating-to-v6.mdx

@@ -0,0 +1,111 @@
+# Migrating to v6
+
+## `onAdEvent` Removed
+
+`onAdEvent` had two problems:
+
+- Only one listener could be registered to an ad instance. Attempting to register a second listener replaced previous listeners
+- There were type conflicts around the event payload because typescript didn't know which event was sent to the listener
+
+In order to resolve these problems, `onAdEvent` is replaced by `addAdEventListener` and `addAdEventsListener`.
+
+### `addAdEventListener`
+
+With each call to `addAdEventListener`, you add a listener for one specific event type. The event type to listen for is the first argument and your event handler is the second argument. The type event payload type for the handler is automatically inferred from the event type you passed.
+
+```diff
+ import {
+   AdEventType,
+   RewardedAd,
+   RewardedAdEventType
+ } from 'react-native-google-mobile-ads';
+
+ const rewardedAd = RewardedAd.createForAdRequest('...');
+-rewardedAd.onAdEvent((type, error, reward) => {
+-  if (type === RewardedAdEventType.LOADED) {
+-    console.log('Ad has loaded');
+-  }
+-  if (type === RewardedAdEventType.EARNED_REWARD) {
+-    console.log('User earned reward of ', reward);
+-  }
+-  if (type === AdEventType.ERROR) {
+-    console.log('Ad failed to load with error: ', error);
+-  }
+-}
++rewardedAd.addAdEventListener(RewardedAdEventType.LOADED, () => {
++  console.log('Ad has loaded');
++});
++rewardedAd.addAdEventListener(RewardedAdEventType.EARNED_REWARD, (reward) => {
++  console.log('User earned reward of ', reward);
++});
++rewardedAd.addAdEventListener(AdEventType.ERROR, (error) => {
++  console.log('Ad failed to load with error: ', error);
++});
+```
+
+To unsubscribe from an event, call the function returned from `addAdEventListener`.
+
+```js
+const unsubscribe = interstitialAd.addAdEventListener(AdEventType.LOADED, () => {
+  console.log('Ad has loaded');
+});
+
+// Sometime later...
+unsubscribe();
+```
+
+### `addAdEventsListener`
+
+With `addAdEventsListener`, you can listen for all of event types as legacy `onAdEvent` did. The handler now passes an object with event type and payload. You have to cast the payload to a corresponding type in order to use in typescript.
+
+```diff
+import {
+  AdEventType,
+  RewardedAd,
+  RewardedAdEventType,
+  RewardedAdReward
+} from 'react-native-google-mobile-ads';
+
+const rewardedAd = RewardedAd.createForAdRequest('...');
+-rewardedAd.onAdEvent((type, error, reward) => {
++rewardedAd.addAdEventsListener(({ type, payload }) => {
+   if (type === RewardedAdEventType.LOADED) {
+     console.log('Ad has loaded');
+   }
+   if (type === RewardedAdEventType.EARNED_REWARD) {
++    const reward = payload as RewardedAdReward;
+     console.log(`User earned reward, name: ${reward.name}, amount: ${reward.amount}`);
+   }
+   if (type === AdEventType.ERROR) {
++    const error = payload as Error;
+     console.log('Ad failed to load with error: ', error.message);
+   }
+ }
+```
+
+To unsubscribe from events, call the function returned from `addAdEventsListener`.
+
+```js
+const unsubscribe = interstitialAd.addAdEventsListener(({ type, payload }) => {
+  console.log('Ad event: ', type, payload);
+});
+
+// Sometime later...
+unsubscribe();
+```
+
+### `removeAllListeners`
+
+You can remove all listeners registered with `addAdEventListener` and `addAdEventsListener` by calling `removeAllListeners` method.
+
+```js
+interstitialAd.addAdEventListener(AdEventType.LOADED, () => {
+  console.log('Ad has loaded');
+});
+interstitialAd.addAdEventsListener(({ type, payload }) => {
+  console.log('Ad event: ', type, payload);
+});
+
+// Sometime later...
+interstitialAd.removeAllListeners();
+```