User Messaging Platform

Obtaining Consent with the User Messaging Platform

Important: You must have a Funding Choices account linked to your AdMob account.

To create a Funding Choices account, go to Privacy & messaging in the AdMob UI and select Go to Funding Choices. The Funding Choices account is then created automatically in the background.

Before attempting to integrate the SDK you should ensure Funding Choices is enabled on your application and that you have created at least one form.

Introduction

Under the Google EU User Consent Policy, you must make certain disclosures to your users in the European Economic Area (EEA) along with the UK 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).

To support publishers in meeting their duties under this policy, Google offers the User Messaging Platform (UMP) SDK, which replaces the previous open source Consent SDK. The UMP SDK has been updated to support the latest IAB standards. We've also simplified the process of setting up consent forms and listing ad providers. All of these configurations can now conveniently be handled in the Funding Choices UI.

It is a best practice to load a form every time the user launches your app, even if you determine consent is not required, so that the form is ready to display in case the user wishes to change their consent setting.

This guide walks you through how to install the SDK, implement the IAB solutions, and enable testing features.

Usage

Request Consent Information

You retrieve the consent information through the ConsentInformation instance accessible via:

var consentInformation:ConsentInformation = Adverts.service.ump.getConsentInformation();

This object has the consent information including:

  • consentInformation.getConsentStatus(): The current user consent status (see ConsentStatus constants);
  • consentInformation.getConsentType(): The type of consent (see ConsentType constants);
  • consentInformation.isConsentFormAvailable(): Whether a form is available to be loaded and displayed to the user;

It is recommended that you request an update of the consent information at every app launch. This will determine whether or not your user needs to provide consent.

To update consent information call the requestConsentInfoUpdate() function on the consent information object.

var params:ConsentRequestParameters = new ConsentRequestParameters();
consentInformation.requestConsentInfoUpdate( params );

This will dispatch one of two possible events:

  • ConsentInformationEvent.CONSENT_INFO_UPDATE_SUCCESS: When the consent information was updated successfully;
  • ConsentInformationEvent.CONSENT_INFO_UPDATE_FAILURE: When there was an error updating the consent information;
var consentInformation:ConsentInformation = Adverts.service.ump.getConsentInformation();
consentInformation.addEventListener( ConsentInformationEvent.CONSENT_INFO_UPDATE_SUCCESS, updateSuccessHandler );
consentInformation.addEventListener( ConsentInformationEvent.CONSENT_INFO_UPDATE_FAILURE, updateFailureHandler );
var params:ConsentRequestParameters = new ConsentRequestParameters();
consentInformation.requestConsentInfoUpdate( params );
function updateSuccessHandler( event:ConsentInformationEvent ):void
{
// consent information has been updated
}
function updateFailureHandler( event:ConsentInformationEvent ):void
{
trace( "ERROR: [" + event.error.errorID + "] " + event.error.message );
}

Load a form if available

Once you've determined that you will ask a user for consent, the next step is to determine if a form is available.

There are a variety of reasons why a form may not be available, such as:

  • The user has limited ad tracking enabled.
  • You tagged the user as under the age of consent.

To check if a form is available, use the isConsentFormAvailable() method on the ConsentInformation instance.

if (consentInformation.isConsentFormAvailable())
{
// A form is available to load
Adverts.service.ump.addEventListener( UserMessagingPlatformEvent.CONSENT_FORM_LOAD_SUCCESS, loadFormSuccessHandler );
Adverts.service.ump.addEventListener( UserMessagingPlatformEvent.CONSENT_FORM_LOAD_FAILURE, loadFormFailureHandler );
Adverts.service.ump.loadConsentForm();
}

To load the form call the loadConsentForm() of the UserMessagingPlatform instance. This will dispatch one of two possible events:

  • UserMessagingPlatformEvent.CONSENT_FORM_LOAD_SUCCESS: When the form has been loaded and is ready to be shown;
  • UserMessagingPlatformEvent.CONSENT_FORM_LOAD_FAILURE: When an error occurred, try again later to load the form successfully before attempting to show;
if (consentInformation.isConsentFormAvailable())
{
Adverts.service.ump.addEventListener( UserMessagingPlatformEvent.CONSENT_FORM_LOAD_SUCCESS, loadFormSuccessHandler );
Adverts.service.ump.addEventListener( UserMessagingPlatformEvent.CONSENT_FORM_LOAD_FAILURE, loadFormFailureHandler );
Adverts.service.ump.loadConsentForm();
}
function loadFormSuccessHandler( event:UserMessagingPlatformEvent ):void
{
// Form loaded and ready to be shown
}
function loadFormFailureHandler( event:UserMessagingPlatformEvent ):void
{
// An error occurred
}

Present the form if required

To present the form use the showConsentForm() on the UserMessagingPlatform instance.

Adverts.service.ump.showConsentForm();

You should determine if the user requires consent prior to presenting the form. To check if consent is required, check the getConsentStatus() method on the ConsentInformation object, which returns an value from the ConsentStatus class. There are four possible values:

  • ConsentStatus.UNKNOWN: Unknown consent status.
  • ConsentStatus.REQUIRED: User consent required but not yet obtained.
  • ConsentStatus.NOT_REQUIRED: User consent not required. For example, the user is not in the EEA or the UK.
  • ConsentStatus.OBTAINED: User consent obtained. Personalization not defined.

For example:

function loadFormSuccessHandler( event:UserMessagingPlatformEvent ):void
{
// Form loaded and ready to be shown
if (Adverts.service.ump.getConsentInformation().getConsentStatus() == ConsentStatus.REQUIRED)
{
Adverts.service.ump.showConsentForm();
}
}

You can also use the form to give your user the option to change their consent status. You may wish to do this in a settings screen, and call the showConsentForm() to present the form so the user can change their consent as required.

The showConsentForm() process will dispatch the ConsentInformationEvent.CONSENT_FORM_DISMISSED event when the consent form was dismissed.

Adverts.service.ump.addEventListener( UserMessagingPlatformEvent.CONSENT_FORM_DISMISSED, formDismissedHandler );
Adverts.service.ump.showConsentForm();
function formDismissedHandler( event:UserMessagingPlatformEvent ):void
{
// Handle form dismissal
}

Testing

Force a geography

The UMP SDK provides a simple way to test your app's behavior as though the device was located in the EEA or UK using the debugGeography.

You will need to provide your test device's hashed ID in your app's debug settings to use the debug functionality. If you call requestConsentUpdate() without setting this value, your app will log the required ID hash when run to the native device log.

var params:ConsentRequestParameters = new ConsentRequestParameters()
.setTagForUnderAgeOfConsent( false )
.setConsentDebugSettings(
new ConsentDebugSettings()
.addTestDeviceHashedId( "TEST-DEVICE-HASHED-ID" )
.setDebugGeography( com.distriqt.extension.adverts.ump.DebugGeography.DEBUG_GEOGRAPHY_EEA )
)
;
Adverts.service.ump.getConsentInformation()
.requestConsentInfoUpdate( params );

To force the SDK to treat the device as though it is not in the EEA or UK, use DEBUG_GEOGRAPHY_NOT_EEA. Note that debug settings only work on test devices. Emulators do not need to be added to the device id list as they have testing enabled by default.

Reset

In testing your app with the UMP SDK, you may find it helpful to reset the state of the consent SDK so that you can simulate a user's first install experience. The SDK provides the reset() method of the ConsentInformation interface to do this.

Adverts.service.ump.getConsentInformation().reset();

You should also call reset if you decide to remove the UMP SDK completely from your project.

Delay app measurement (optional)

By default, the Google Mobile Ads SDK initializes app measurement and begins sending user-level event data to Google immediately when the app starts. This initialization behavior ensures you can enable AdMob user metrics without making additional code changes.

However, if your app requires user consent before these events can be sent, you can delay app measurement until you explicitly initialize the Mobile Ads SDK or load an ad.

Android

To delay app measurement, add the following <meta-data> tag in your manifest additions, inside the <application> node:

<!-- Delay app measurement until MobileAds.initialize() is called. -->
<meta-data
android:name="com.google.android.gms.ads.DELAY_APP_MEASUREMENT_INIT"
android:value="true"/>

iOS

To delay app measurement, add the GADDelayAppMeasurementInit key with a boolean value of true to your app’s InfoAdditions:

<key>GADDelayAppMeasurementInit</key>
<true/>