react-native-google-mobile-ads 4.2.0 → 5.1.0

package/docs/european-user-consent.mdx

@@ -6,16 +6,9 @@ other local storage, where legally required, and to use personal data (such as `
 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 Consent SDK for both
+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.
 
-The `AdsConsent` helper & AdMob module provides out of the box support for:
-
-- Requesting consent for multiple publisher IDs.
-- Showing a Google-rendered consent form, listing all providers on your enabled mediation networks.
-- Manually handling user consent if you prefer not to use the Google-rendered consent form.
-- Forwarding your user consent status onto AdMob ad requests.
-
 ## Understanding AdMob Ads
 
 Ads served by Google can be categorized as personalized or non-personalized, both requiring consent from users in the EEA. By default,
@@ -25,8 +18,6 @@ ad requests to Google serve personalized ads, with ad selection based on the use
 
 ## Handling consent
 
-The following steps show the various methods and ways of handling consent within your app.
-
 ### 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.
@@ -54,156 +45,105 @@ npx react-native run-ios
 npx react-native run-android
 ```
 
-### Requesting consent information
+### App Tracking Transparency
 
-It is recommended you request consent information each time your application starts. The Consent SDK stores the users consent status
-based on the state of your AdMob network. If the state changes (e.g. a new mediation provider is added) the SDK automatically
-invalidates the consent status (setting is to "UNKNOWN").
+If you want to handle Apple's App Tracking Transparency requirements, ensure you've configured and published your [ATT message](https://developers.google.com/admob/ump/ios/quick-start#app_tracking_transparency) in your Google AdMob account.
+Also, within your projects `app.json` file, you have to use the `user_tracking_usage_description` to to describe your usage:
+
+```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."
+  }
+}
+```
 
-The `AdsConsent` helper provides a promised based method to return the users consent status called `requestInfoUpdate`. This method
-accepts an array of publisher IDs, which are used by the Consent SDK to determine the users consent status.
+Once set, rebuild your application.
 
-Your own publisher ID can be found on the [Google AdMob dashboard](https://apps.admob.com/v2/settings) under "Settings > Account Information":
+### Requesting consent information
 
-![Publisher ID](https://prismic-io.s3.amazonaws.com/invertase%2Fbcb7e7d6-2bb3-4e8c-8e6e-be99d6bc4f56_new+project+%2816%29.jpg)
+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.
 
-To request consent, call the method as early as possible within your app before presenting any ads:
+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(['pub-6189033257628123']);
+const consentInfo = await AdsConsent.requestInfoUpdate();
 ```
 
-The result of the method returns an `AdsConsentInfo` interface, which provides information about the users status and location:
+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 3 outcomes:
-  - `UNKNOWN`: The user has not yet given consent, or has been invalidated since the last time they gave consent.
-  - `NON_PERSONALIZED`: The user gave consent to see non-personalized ads only.
-  - `PERSONALIZED`: The user gave consent to see personalized ads.
-- **isRequestLocationInEeaOrUnknown**: A boolean value. If `true` the users location is within the EEA or is unknown.
-
-The combination of status and location allows you to handle the next steps for requesting consent, if required:
-
-1. If the users location is within the EEA or unknown, and their status is unknown, you must request consent before showing any ads.
-2. If the users location is within the EEA or unknown, and their status is **not** unknown, you can show only the ad personalization they have requested.
-3. If the users location is outside of the EEA, you do not have to give consent.
+- **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.
 
 ### Gathering user consent
 
-Now we understand the consent status of the user, we can gather their consent (if required). This can be done in two ways:
-
-1. Using a Google-rendered consent form.
-2. Using a custom method.
-
-If you are aware that users are under the age of consent in Europe, it is possible to set this using the `setTagForUnderAgeOfConsent`
-method (TFUA). Once the setting is enabled, the Google-rendered consent form will fail to load. All ad requests that include
-TFUA will be made ineligible for personalized advertising and remarketing. TFUA disables requests to third-party ad technology
-providers, such as ad measurement pixels and third-party ad servers.
-
-To remove this setting, pass `false` to the method.
-
-#### 1. Google-rendered consent form
-
-The Google-rendered consent form is a full-screen configurable form that displays over your app content.
-You can configure the form to present the user with combinations of the following options:
-
-- Consent to view personalized ads
-- Consent to view non-personalized ads
-- Use a paid version of the app instead of viewing ads
-
-You should review the consent text carefully: what appears by default is a message that might be appropriate if you use
-Google to monetize your app; but Google cannot provide legal advice on the consent text that is appropriate for you.
-To update consent text of the Google-rendered consent form, modify the `consentform.html` file included in the Consent SDK as required.
-
-> An [example of a Google-rendered](https://developers.google.com/admob/images/android_eu_consent_form.png) consent form.
-
-To show the consent form, the `AdsConsent` helper provides a `showForm` method, which takes options to configure the form.
-You must provide a privacy policy URL.
+To request consent, call these methods as early as possible within your app before presenting any ads.
+Once the user has selected their preference, the `showForm` method returns an `AdsConsentFormResult` interface, containing the updated consent status:
 
 ```js
 import { AdsConsent, AdsConsentStatus } from 'react-native-google-mobile-ads';
 
-const consentInfo = await AdsConsent.requestInfoUpdate(['pub-6189033257628123']);
-
-if (
-  consentInfo.isRequestLocationInEeaOrUnknown &&
-  consentInfo.status === AdsConsentStatus.UNKNOWN
-) {
-  const formResult = await AdsConsent.showForm({
-    privacyPolicy: 'https://invertase.io/privacy-policy',
-    withPersonalizedAds: true,
-    withNonPersonalizedAds: true,
-    withAdFree: true,
-  });
-}
-```
-
-Once the user has selected their preference, the `formResult` contains their status and whether or not they prefer an
-ad-free option of your application (if enabled):
+const consentInfo = await AdsConsent.requestInfoUpdate();
 
-```js
-const formResult = await AdsConsent.showForm({
-  privacyPolicy: 'https://invertase.io/privacy-policy',
-  withPersonalizedAds: true,
-  withNonPersonalizedAds: true,
-  withAdFree: true,
-});
-
-if (formResult.userPrefersAdFree) {
-  // Handle the users request, e.g. redirect to a paid for version of the app
+if (consentInfo.isConsentFormAvailable && consentInfo.status === AdsConsentStatus.REQUIRED) {
+  const { status } = await AdsConsent.showForm();
 }
-
-// The user requested non-personalized or personalized ads
-const status = formResult.status;
 ```
 
-The `formResult.status` provides feedback on whether the user consented to personalized ads, or non-personalized ads.
-It is important that you forward this status onto all ad requests (see below).
-
 > 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.
 
-#### 2. Custom consent method
+### Inspecting consent choices
 
-If you wish to implement your own consent flow, the `AdsConsent` helper provides the tools needed to accomplish this.
-Depending on your requirements, a list of the enabled network mediation providers for the AdMob App ID can be returned and shown
-to the user via the `getAdProviders` method:
+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 though.
+Especially since the Google Mobile Ads SDK won't show any ads if the user didn't give consent to store and/or access information on the device.
+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 providers = await AdsConsent.getAdProviders();
-```
-
-Each provider is an interface of `AdProvider`, containing information such as their company ID, company name and privacy policy URL.
-Using this information you can request consent from your users.
-
-Once consent has been returned, the Consent SDK needs to be aware of the custom user consent status. This can be forwarded on using the
-`setStatus` method, for example:
-
-```js
-import { AdsConsent, AdsConsentStatus } from 'react-native-google-mobile-ads';
-
-// After getting user consent...
-await AdsConsent.setStatus(AdsConsentStatus.PERSONALIZED);
+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,
+   * the Google Mobile Ads SDK won't serve ads.
+   */
+}
 ```
 
-To invalidate the users consent status (e.g. if the providers list changes since their last consent), set the status back to
-`UNKNOWN`. When your application next boots, you can get the users previous consent status using the `getStatus` method.
-
 ### 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
-Consent SDK.
+UMP SDK.
 
-If using a real device, ensure you whitelist it using 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). Once found,
-call the `addTestDevice(deviceId)` method.
+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 `setDebugGeography` method. It accepts 3 values:
+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.
@@ -214,45 +154,16 @@ For example:
 ```js
 import { AdsConsent, AdsConsentDebugGeography } from 'react-native-google-mobile-ads';
 
-await AdsConsent.setDebugGeography(AdsConsentDebugGeography.EEA);
+const consentInfo = await AdsConsent.requestInfoUpdate({
+  debugGeography: AdsConsentDebugGeography.EEA,
+  testDeviceIdentifiers: ['TEST-DEVICE-HASHED-ID'],
+});
 ```
 
-> Always ensure debug information is removed for production apps!
-
-### Forwarding the consent status to ads
-
-Assuming the user is within the EEA and has provided consent, their status needs to be forwarded to every ad request we
-make in our application.
-
-> If the user is within the EEA and has not given consent, do not display AdMob ads (even non-personalized).
-
-Taking a Rewarded Video as an example, we can apply the users consent when our ad is loaded via the `RequestOptions`. For example:
+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, RewardedAd } from 'react-native-google-mobile-ads';
-
-const status = await AdsConsent.getStatus();
+import { AdsConsent } from 'react-native-google-mobile-ads';
 
-const rewardedAd = RewardedAd.createForAdRequest('AD_UNIT_ID', {
-  requestNonPersonalizedAdsOnly: status === AdsConsentStatus.NON_PERSONALIZED,
-});
+AdsConsent.reset();
 ```
-
-The requested ad URL via the SDK will send a request with an additional parameter `&npa=1`, which will return a
-non-personalized ad.
-
-### Troubleshooting
-
-#### "Could not parse Event FE preflight response."
-
-This is a common error which occurs on both Android & iOS when making a request to display a Google-rendered consent form. Unfortunately the reasoning for this error is generic, making it hard to debug. There are a number of steps to check which are usually the cause for this error:
-
-- The AdMob App ID is incorrect: Ensure you have entered the correct ID into the `app.json` file under the `android_app_id` or `ios_app_id` key in the `react-native-google-mobile-ads` config.
-- A publisher ID is incorrect: Ensure your entered publisher IDs are correct.
-  - The publisher ID needs to be available on the same account as your AdMob App ID.
-- The user is outside of the EEA: If a user does not need to provide consent, the form request will error. Ensure you have checked the users status via `requestInfoUpdate`. If using an emulator, ensure you set a debug location via `setDebugGeography`.
-- Your AdMob account is not valid:
-  - Your account is disabled: This can occur if Google notices you have duplicate accounts. They will email you about this, and block you from entering the dashboard.
-  - You have provided invalid payment information: If your account has no payment information set up, this seems to cause this error to trigger.
-
-If you are still struggling to present the consent form, reach out to AdMob support to investigate your account status via https://support.google.com/admob

package/docs/index.mdx

@@ -7,21 +7,21 @@ yarn add react-native-google-mobile-ads
 
 > On Android, before releasing your app, you must select _Yes, my app contains ads_ in the Google Play Store, Policy, App content, Manage under Ads.
 
-# What does it do
+## What does it do
 
 The AdMob module allows you to display adverts to your users. All adverts are served over the Google AdMob network, meaning
 a [Google AdMob account](https://apps.admob.com) is required.
 
 <YouTube id="9qCxo0D-Sak" />
 
-The module supports three types of Ads:
+The module supports four types of Ads:
 
 1. Full screen [App Open Ads](/displaying-ads#app-open-ads).
 2. Full screen [Interstitial Ads](/displaying-ads#interstitial-ads).
 3. Full screen [Rewarded Ads](/displaying-ads#rewarded-ads).
 4. Component based [Banner Ads](/displaying-ads#banner-ads).
 
-# Getting Started
+## Getting Started
 
 A number of steps must be taken and considered before you start serving adverts to your users:
 
@@ -33,7 +33,7 @@ A number of steps must be taken and considered before you start serving adverts
   - [Test ads](#test-ads)
 - [Next Steps](#next-steps)
 
-## Setting up Google AdMob
+### Setting up Google AdMob
 
 Before you are able to display ads to your users, you must have a [Google AdMob account](https://apps.admob.com). Under the
 "Apps" menu item, create or choose an existing Android/iOS app. Each app platform exposes a unique account ID which needs to
@@ -62,14 +62,14 @@ For the changes to take effect, rebuild your project:
 
 ```bash
 # For iOS
-cd ios/ && pod install
+npx pod-install
 npx react-native run-ios
 
 # For Android
 npx react-native run-android
 ```
 
-## Configure outbound requests
+### Configure outbound requests
 
 If the default ad settings are not correct for your app, you can provide settings that will apply to all ad requests.
 
@@ -93,8 +93,8 @@ mobileAds()
     // manner suitable for users under the age of consent.
     tagForUnderAgeOfConsent: true,
 
-    // An array of test device IDs to whitelist.
-    testDeviceIdentifiers: ["EMULATOR"]
+    // An array of test device IDs to allow.
+    testDeviceIdentifiers: ['EMULATOR'],
   })
   .then(() => {
     // Request config successfully set!
@@ -103,37 +103,37 @@ mobileAds()
 
 To learn more about the request configuration settings, view the [`RequestConfiguration`](/reference/admob/requestconfiguration) documentation.
 
-## Initialize the Google Mobile Ads SDK
+### Initialize the Google Mobile Ads SDK
 
 Before loading ads, have your app initialize the Google Mobile Ads SDK by calling `initialize` which initializes the SDK and returns a promise once initialization is complete (or after a 30-second timeout).
 This needs to be done only once, ideally at app launch.
 
 > ⚠️ **Warning:** Ads may be preloaded by the Mobile Ads SDK or mediation partner SDKs upon calling `initialize`.
-If you need to obtain consent from users in the European Economic Area (EEA), set any request-specific flags (such as tagForChildDirectedTreatment), or otherwise take action before loading ads, ensure you do so before initializing the Mobile Ads SDK.
+> If you need to obtain consent from users in the European Economic Area (EEA), set any request-specific flags (such as tagForChildDirectedTreatment), or otherwise take action before loading ads, ensure you do so before initializing the Mobile Ads SDK.
 
 ```js
 import mobileAds from 'react-native-google-mobile-ads';
 
 mobileAds()
   .initialize()
-  .then((adapterStatuses) => {
+  .then(adapterStatuses => {
     // Initialization complete!
   });
 ```
 
 If you are using mediation, you may wish to wait until the promise is settled before loading ads, as this will ensure that all mediation adapters are initialized.
 
-## European User Consent
+### European User Consent
 
 Out of the box, AdMob does not handle any related regulations which you may need to enforce on your application.
 It is up to the developer to implement and handle this on a user-by-user basis. You must consent to EEA users
 being served both personalized and non-personalized adverts before showing them. For more information, see
-[Requesting Consent from European Users](https://developers.google.com/admob/android/eu-consent).
+[Obtaining Consent with the User Messaging Platform](https://developers.google.com/admob/ump/android/quick-start).
 
-The AdMob module provides a `AdConsent` helper to help developers quickly implement consent flows within their application.
+The AdMob module provides a `AdsConsent` helper to help developers quickly implement consent flows within their application.
 See the [European User Consent page](/european-user-consent) for full examples of how to integrate the helper into your application.
 
-## Test ads
+### Test ads
 
 Whilst developing your app with AdMob, you'll want to make sure you use test ads rather than production ads from your
 Google AdMob account - otherwise your account may be disabled!
@@ -157,7 +157,7 @@ RewardedAd.createForAdRequest(TestIds.REWARDED);
 <BannerAd unitId={TestIds.BANNER} />
 ```
 
-# Next Steps
+## Next Steps
 
 Now the basics of setting up and configuring AdMob have been explained, we can go ahead and start to display different
 adverts to our users. The AdMob module provides integration with three different types:

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.json

@@ -4,7 +4,9 @@
   "sidebar": [
     ["Installation", "/"],
     ["Displaying Ads", "/displaying-ads"],
+    ["Displaying Ads via Hook", "/displaying-ads-hook"],
     ["European User Consent", "/european-user-consent"],
-    ["Common Reasons For Ads Not Showing", "/common-reasons-for-ads-not-showing"]
+    ["Common Reasons For Ads Not Showing", "/common-reasons-for-ads-not-showing"],
+    ["Migrating to v5", "/migrating-to-v5"]
   ]
-} 
+}

package/ios/RNGoogleMobileAds/RNGoogleMobileAdsConsentModule.h

@@ -18,7 +18,6 @@
 
 #import <Foundation/Foundation.h>
 
-#import <PersonalizedAdConsent/PersonalizedAdConsent.h>
 #import <React/RCTBridgeModule.h>
 
 @interface RNGoogleMobileAdsConsentModule : NSObject <RCTBridgeModule>