# 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 or non-personalized, both requiring consent from users in the EEA. By default,
ad requests to Google serve personalized ads, with ad selection based on the user's previously collected data. Users outside of the EEA do not require consent.

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

## Handling consent

### 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).

Within your projects `app.json` file, set the `delay_app_measurement_init` to `true` to delay app measurement:

```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
  }
}
```

Once set, rebuild your application:

```bash
# For iOS
npx react-native run-ios

# For Android
npx react-native run-android
```

### App Tracking Transparency

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."
  }
}
```

Once set, rebuild your application.

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

### Gathering user consent

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();

if (
  consentInfo.isConsentFormAvailable &&
  consentInfo.status === AdsConsentStatus.REQUIRED
) {
  const { status } = await AdsConsent.showForm();
}
```

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

### 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()
```