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

package/docs/european-user-consent.mdx

@@ -0,0 +1,315 @@
+# European User Consent
+
+Under the Google [EU User Consent Policy](https://www.google.com/about/company/consentstaging.html), you must make
+certain disclosures to your users in the European Economic Area (EEA) and obtain their consent to use cookies or
+other local storage, where legally required, and to use personal data (such as `AdID`) to serve ads. This policy
+reflects the requirements of the `EU ePrivacy Directive` and the `General Data Protection Regulation` (GDPR).
+
+The React Native Google Mobile Ads module provides out of the box support for helping to manage your users consent
+within your application. The `AdsConsent` helper which comes with the module wraps the Google UMP SDK for both
+Android & iOS, and provides a single JavaScript interface for both platforms.
+
+## Understanding AdMob Ads
+
+Ads served by Google can be categorized as personalized, non-personalized, Limited ads and technical ads. To understand more about what ads can be served based on a
+user's consent choices, see Ad serving modes ([Android](https://developers.google.com/admob/android/privacy/ad-serving-modes) / [iOS](https://developers.google.com/admob/ios/privacy/ad-serving-modes)). 
+
+<Info>
+The `AdsConsent` helper only provides you with the tools for requesting consent, it is up to the developer to ensure the consent status is reflected throughout the app.
+</Info>
+
+## Handling consent
+
+To setup and configure ads consent collection, start by enabling and configuring GDPR and IDFA messaging in the [Privacy & messaging section of AdMob's Web Console](https://apps.admob.com/v2/privacymessaging).
+
+<Tabs groupId="framework" values={[{label: 'React Native', value: 'bare'}, {label: 'Expo', value: 'expo'}]}>
+<TabItem value="bare">
+
+For Android, add the following rule into `android/app/proguard-rules.pro`:
+
+```
+-keep class com.google.android.gms.internal.consent_sdk.** { *; }
+```
+
+</TabItem>
+<TabItem value="expo">
+
+Add the `extraProguardRules` property to `app.json`, `app.config.js`, or `app.config.ts` file as described in the [Expo documentation](https://docs.expo.dev/versions/latest/sdk/build-properties/#pluginconfigtypeandroid):
+
+```json
+// <project-root>/app.json
+{
+  "expo": {
+    "plugins": [
+      [
+        "expo-build-properties",
+        {
+          "android": {
+            "extraProguardRules": "-keep class com.google.android.gms.internal.consent_sdk.** { *; }"
+          }
+        }
+      ]
+    ]
+  }
+}
+```
+
+You'll need to generate a new development build before using it.
+
+</TabItem>
+</Tabs>
+
+### Delaying app measurement
+
+By default, the Google Mobile Ads SDK initializes app measurement and begins sending user-level event data to Google immediately when the app starts.
+If your app will be used by users within the EEA, it is important you prevent app measurement until your first ad has been requested (after consent).
+
+<Tabs groupId="framework" values={[{label: 'React Native', value: 'bare'}, {label: 'Expo', value: 'expo'}]}>
+<TabItem value="bare">
+
+Within your projects `app.json` file, set the `delay_app_measurement_init` to `true` to delay app measurement:
+
+```json
+// <project-root>/app.json
+{
+  "react-native-google-mobile-ads": {
+    "android_app_id": "ca-app-pub-xxxxxxxx~xxxxxxxx",
+    "ios_app_id": "ca-app-pub-xxxxxxxx~xxxxxxxx",
+    "delay_app_measurement_init": true
+  }
+}
+```
+
+</TabItem>
+<TabItem value="expo">
+
+Within your projects `app.json`, `app.config.js`, or `app.config.ts` file, set the `delayAppMeasurementInit` to `true` to delay app measurement:
+
+```json
+// <project-root>/app.json
+{
+  "expo": {
+    "plugins": [
+      [
+        "react-native-google-mobile-ads",
+        {
+          "androidAppId": "ca-app-pub-xxxxxxxx~xxxxxxxx",
+          "iosAppId": "ca-app-pub-xxxxxxxx~xxxxxxxx",
+          "delayAppMeasurementInit": true
+        }
+      ]
+    ]
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
+Once set, rebuild your application.
+
+### App Tracking Transparency
+
+If you configure an [ATT message](https://support.google.com/admob/answer/10115331) in your Google AdMob account, the UMP SDK will automatically handle the ATT alert.
+This will also show an IDFA explainer message. If you don't want to show an explainer message you can show the ATT alert [manually](https://docs.page/invertase/react-native-google-mobile-ads#app-tracking-transparency-ios).
+Also, within your projects configuration file, you have to provide a user tracking usage description (once set, rebuild your application):
+
+<Tabs groupId="framework" values={[{label: 'React Native', value: 'bare'}, {label: 'Expo', value: 'expo'}]}>
+<TabItem value="bare">
+
+```json
+// <project-root>/app.json
+{
+  "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."
+  }
+}
+```
+
+</TabItem>
+<TabItem value="expo">
+
+```json
+// <project-root>/app.json
+{
+  "expo": {
+    "plugins": [
+      [
+        "react-native-google-mobile-ads",
+        {
+          "androidAppId": "ca-app-pub-xxxxxxxx~xxxxxxxx",
+          "iosAppId": "ca-app-pub-xxxxxxxx~xxxxxxxx",
+          "userTrackingUsageDescription": "This identifier will be used to deliver personalized ads to you."
+        }
+      ]
+    ]
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
+### Requesting consent information
+
+It is recommended you request consent information each time your application starts to determine if the consent modal should be shown, e.g. due to provider changes.
+
+The `AdsConsent` helper provides a promise based method to return the users consent status called `requestInfoUpdate`.
+
+```js
+import { AdsConsent } from 'react-native-google-mobile-ads';
+
+const consentInfo = await AdsConsent.requestInfoUpdate();
+```
+
+The method returns an `AdsConsentInfo` interface, which provides information about consent form availability and the users consent status:
+
+- **status**: The status can be one of 4 outcomes:
+  - `UNKNOWN`: Unknown consent status.
+  - `REQUIRED`: User consent required but not yet obtained.
+  - `NOT_REQUIRED`: User consent not required.
+  - `OBTAINED`: User consent already obtained.
+- **isConsentFormAvailable**: A boolean value. If `true` a consent form is available.
+
+**Note:** The return status of this call is the status of _form presentation and response collection_, **not
+the the actual user consent**. It simply indicates if you now have a consent response to decode.
+(_i.e._ if user consent is **required**, the form has been presented, and user has
+**denied** the consent, the status returned by this method will be `OBTAINED`,
+and not `REQUIRED` as some may expect). To check the actual consent status
+see [Inspecting consent choices](/european-user-consent/#inspecting-consent-choices) below.
+
+### Gathering user consent
+
+You should request an update of the user's consent information at every app launch, using `requestInfoUpdate`.
+This determines whether your user needs to provide consent if they haven't done so already, or if their consent has expired.
+
+After you have received the most up-to-date consent status, call `loadAndShowConsentFormIfRequired` to load a consent form.
+If the consent status is required, the SDK loads a form and immediately presents it.
+The completion handler is called after the form is dismissed. If consent is not required, the completion handler is called immediately.
+
+To make it easier we added a helper method `gatherConsent` that combines requesting consent information and loading/presenting a consent form if necessary.
+
+Before requesting ads in your app, check if you have gathered consent aligned with your app's configured messages using `canRequestAds`.
+If an error occurs during the consent gathering process, you should still attempt to request ads.
+The UMP SDK uses the consent status from the previous session.
+
+**Note:** For more information on when `canRequestAds` is `true` or `false`, see the reference documentation for [Android](https://developers.google.com/admob/android/reference/privacy/com/google/android/ump/ConsentInformation#canRequestAds()) /
+[iOS](https://developers.google.com/admob/ios/privacy/api/reference/Classes/UMPConsentInformation#canrequestads).
+
+```js
+import mobileAds, { AdsConsent, AdsConsentStatus } from 'react-native-google-mobile-ads';
+
+const isMobileAdsStartCalledRef = useRef(false);
+
+useEffect(() => {
+  // Request consent information and load/present a consent form if necessary.
+  AdsConsent.gatherConsent()
+    .then(startGoogleMobileAdsSDK)
+    .catch((error) => console.error('Consent gathering failed:', error));
+
+  // This sample attempts to load ads using consent obtained in the previous session.
+  // We intentionally use .then() chaining (instead of await) to ensure parallel execution.
+  startGoogleMobileAdsSDK();
+}, []);
+
+async function startGoogleMobileAdsSDK() {
+  const {canRequestAds} = await AdsConsent.getConsentInfo();
+  if (!canRequestAds || isMobileAdsStartCalledRef.current) {
+    return;
+  }
+
+  isMobileAdsStartCalledRef.current = true;
+
+  // (Optional, iOS) Handle Apple's App Tracking Transparency manually.
+  const gdprApplies = await AdsConsent.getGdprApplies();
+  const hasConsentForPurposeOne = gdprApplies && (await AdsConsent.getPurposeConsents()).startsWith("1");
+  if (!gdprApplies || hasConsentForPurposeOne) {
+    // Request ATT...
+  }
+
+  // Initialize the Google Mobile Ads SDK.
+  await mobileAds().initialize()
+
+  // Request an ad...
+}
+```
+
+> Do not persist the status. You could however store this locally in application state (e.g. React Context) and update the status on every app launch as it may change.
+
+### Inspecting consent choices
+
+The AdsConsentStatus tells you if you should show the modal to a user or not. Often times you want to run logic based on the user's choices. This library exports a
+method that returns some of the most relevant consent flags to handle common use cases.
+
+```js
+import { AdsConsent } from 'react-native-google-mobile-ads';
+
+const {
+  activelyScanDeviceCharacteristicsForIdentification,
+  applyMarketResearchToGenerateAudienceInsights,
+  createAPersonalisedAdsProfile,
+  createAPersonalisedContentProfile,
+  developAndImproveProducts,
+  measureAdPerformance,
+  measureContentPerformance,
+  selectBasicAds,
+  selectPersonalisedAds,
+  selectPersonalisedContent,
+  storeAndAccessInformationOnDevice,
+  usePreciseGeolocationData,
+} = await AdsConsent.getUserChoices();
+
+if (storeAndAccessInformationOnDevice === false) {
+  // The user declined consent for purpose 1.
+}
+```
+
+**Note:** Don't try to use this functionality to enforce user consent on iOS,
+this will likely result in failed app review upon submission to Apple Store, based on [review guideline 3.2.2.vi](https://developer.apple.com/app-store/review/guidelines/#3.2.2):
+
+> ...Apps should not require users to rate the app, review the app, watch videos, download other apps, tap on advertisements, enable tracking...
+
+### Testing
+
+When developing the consent flow, the behavior of the `AdsConsent` responses may not be reliable due to the environment
+(e.g. using an emulator vs real device). It is possible to set a debug location to test the various responses from the
+UMP SDK.
+
+If using a real device, ensure you add it to the list of allowed devices by passing the device ID, which can be obtained from native logs or using a library
+such as [react-native-device-info](https://github.com/react-native-community/react-native-device-info), to `testDeviceIdentifiers`.
+
+> Emulators are automatically whitelisted.
+
+To set a debug location, use the `debugGeography` key. It accepts 3 values:
+
+- **DISABLED**: Removes any previous debug locations.
+- **EEA**: Set the test device to be within the EEA.
+- **NOT_EEA**: Set the test device to be outside of the EEA.
+
+For example:
+
+```js
+import { AdsConsent, AdsConsentDebugGeography } from 'react-native-google-mobile-ads';
+
+const consentInfo = await AdsConsent.requestInfoUpdate({
+  debugGeography: AdsConsentDebugGeography.EEA,
+  testDeviceIdentifiers: ['TEST-DEVICE-HASHED-ID'],
+});
+```
+
+It is possible to reset the UMP state for test devices. To reset the ATT state you have to delete and reinstall your app though.
+
+```js
+import { AdsConsent } from 'react-native-google-mobile-ads';
+
+AdsConsent.reset();
+```
+
+### Troubleshooting
+
+In case of troubles, double-check the following artifacts:
+* Original documentation for underlying UMP SDK for [Android](https://developers.google.com/admob/ump/android/quick-start) /
+[iOS](https://developers.google.com/admob/ump/ios/quick-start).
+* Google Help Center [European regulations](https://support.google.com/admob/topic/10115026) articles.

package/docs/img/logo_admob_192px.svg

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 22.1.0, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
+<svg version="1.1" id="Content" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 width="192px" height="192px" viewBox="0 0 192 192" enable-background="new 0 0 192 192" xml:space="preserve">
+<rect id="bounding_box_2_" fill="none" width="192" height="192"/>
+<g id="logo_x5F_admob_x5F_192px">
+	<g id="icon_x5F_admob_x5F_192px_2_">
+		<path fill="#FBBC04" d="M92.01,8.26C93.28,8,98.31,8.01,99.51,8c34.25-0.27,81.75,28.87,84.49,84.28v69.18
+			c0,12.45-10.28,22.54-22.77,22.54c-9,0-21.23-11.53-21.23-22.5V92.32c-1.27-18.26-16.07-38.81-40.99-40.36
+			c-1.54-0.1-5.04-0.16-7.01,0.1"/>
+		<path fill="#4285F4" d="M183.98,162c0,12.15-9.85,22-22,22S140,174.15,140,162c0-12.15,9.83-22,21.98-22S183.98,149.85,183.98,162
+			z"/>
+		<path fill="#EA4335" d="M93.2,183.24c12.6,0,22.81-10.02,22.81-22.37c0-12.36-10.46-21.33-23.05-21.33
+			c-0.08,0-0.16,0.01-0.24,0.01c-21.66-1.5-41.92-20.57-40.44-46.71c0,0,0.01-0.13,0.03-0.42c1.25-20.51,18.75-39.12,40.9-40.4l0,0
+			c0,0,0,0,0,0c12.6,0,22.81-9.04,22.81-21.39S105.8,8.25,93.2,8.25c-0.51,0-1.02-0.03-1.53,0C53.46,9.58,8.46,41.37,8.01,95.4v0.33
+			c0,54.83,48.09,87.5,83.93,87.5H93.2z"/>
+	</g>
+</g>
+</svg>

package/docs/impression-level-ad-revenue.mdx

@@ -0,0 +1,41 @@
+# Impression-level ad revenue
+
+[Impression-level ad revenue] helps to calculate more precise data on
+the lifetime value (LTV) of app users. When enabled, AdMob sends back
+the ad revenue for each ad impression shown on the user's device. This
+data can be used to understand users' activities.
+
+To use this feature:
+
+1.  Enable the feature in the AdMob console, as explained in
+    the [Impression-level ad revenue] documentation.
+
+2.  For banner ad components use their `onPaid` prop to setup ad revenue event
+    listeners. It should have the signature `(event: PaidEvent) => void`.
+
+    For «full-screen» ads (app open, interstitial, _etc._) use
+    their `addAdEventListener` methods to setup a listener, and look for
+    the event with type `paid`, which payload will be a `PaidEvent` object.
+
+    For «full-screen» displayed using hooks, the hooks return
+    optional `revenue` value. If present, it keeps the last received `PaidEvent`
+    for the ad.
+
+The `PaidEvent` type is:
+
+```ts
+type PaidEvent = {
+  currency: string;
+  precision: RevenuePrecisions;
+  value: number;
+};
+```
+
+where `RevenuePrecisions` is an enum with keys `ESTIMATED`, `PRECISE`,
+`PUBLISHER_PROVIDED`, and `UNKNOWN`. It can be imported from the library as
+
+```ts
+import { RevenuePrecisions } from 'react-native-google-mobile-ads';
+```
+
+[Impression-level ad revenue]: https://support.google.com/admob/answer/11322405?hl=en