Consent Management UMP

Introduction

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

Google offers the User Messaging Platform (UMP) SDK to support publishers in meeting their duties under this policy. The UMP SDK has been updated to support the latest IAB standards. Plankton offers the same methods and functionalities as UMP and acts as a wrapper to facilitate the use of UMP.

Before you begin

Prerequisites

Complete the Plankton setup
Set up your game in your AdMob account
For Android
- Set Minimum API Level to 24 or higher.
For iOS
- Set Target Minimum iOS Version to 15.0 or higher

note

You can change Minimum and Target versions in Unity from Edit > Project Settings > Player > Other Settings

Create a message type

Create user messages with the GDPR type under the Privacy & messaging tab of your AdMob account. The UMP SDK attempts to display a user message created from the AdMob Application ID set in your project. If no message is configured for your application, the SDK returns an error.

For more details, see About privacy and messaging.

Implementation

In this section you'll find detailed information on how to implement UMP feature of Plankton. Remember to import the Plankton package wherever you need to use it.

using Plankton;

You should request an update of the user's consent information at every app launch, using RequestConsentInfoUpdate. This determines whether your user needs to provide consent if they haven't done so already, or if their consent has expired.

GoogleUmp.RequestConsentInfoUpdate(result => {
    Debug.Log($"Result -> success:{result.success}, error code:{result.error_code}, error message:{result.error_message}");
    // next step: call LoadAndShowConsentFormIfRequired 
});

This method takes a callback argument of type Action<ConsentResults>. The ConsentResults object returned in the callback contains a success field, which indicates whether the consent information update was successful. If success is false, you can check the error_code and error_message fields in ConsentResults to get details about the error that occurred.

warning

Using other ways of checking consent status, such as the cache on your app or a previously saved consent string, could lead to a TCF 3.3 error if consent is expired.

Call LoadAndShowConsentFormIfRequired to load a consent form. If the consent status is required, the SDK loads a form and immediately presents it on the screen. The callback is called after the form is dismissed. If consent is not required, the callback is called immediately.

This method should be called after you have received the most up-to-date consent status (by calling RequestConsentInfoUpdate)

GoogleUmp.LoadAndShowConsentFormIfRequired(result => 
    Debug.Log($"Result -> success:{result.success}, error code:{result.error_code}, error message:{result.error_message}")
);

This method takes a callback argument of type Action<ConsentResults>. The ConsentResults object returned in the callback contains a success field, which indicates whether the loading and showing process of consent was successful. If success is false, you can check the error_code and error_message fields in ConsentResults to get details about the error that occurred.

Request ads

Before requesting ads in your game (if you use Plankton for showing your ads, you need to do this before initializing the ads feature), check if you have obtained consent from the user using CanRequestAds. There are two places you should check:

Once consent has been gathered in the current session (in the callback of LoadAndShowConsentFormIfRequired).
Immediately after you have called RequestConsentInfoUpdate. It is possible consent has been obtained in the previous session. As a latency best practice, we recommend not waiting for the callback to complete so you can start loading ads as soon as possible after your app launches.

bool canRequestAds = GoogleUmp.CanRequestAds();
if (canRequestAds)
    InitializeAds(); // Call Ad.Initialize with your configured builder once.

If consent gathering fails, check GoogleUmp.CanRequestAds() again; the SDK may have usable consent from a previous session. Initialize ads only when this returns true, with a guard to prevent duplicate initialization. On iOS, complete any ATT request before initializing ads.

note

CanRequestAds always returns false until you have called requestConsentInfoUpdate()

warning

Enable Google UMP in Plankton settings before using these APIs. When the dependency is missing, Plankton logs the error and CanRequestAds() returns false; do not use that result to start ads.

Privacy options

Some consent forms require the user to modify their consent at any time. Adhere to the following steps to implement a privacy options button if required.

To accomplish this:

Implement a UI element, such as a button in your game's settings page, that can trigger a privacy options form.
Once LoadAndShowConsentFormIfRequired completes, call IsPrivacyOptionsRequired to determine whether to display the UI element that can present the privacy options form.
When a user interacts with your UI element, call ShowPrivacyOptionsForm to show the form so the user can update their privacy options at any time.

if (GoogleUmp.IsPrivacyOptionsRequired()) {
    // Generate a button in options menu that calls GoogleUmp.ShowPrivacyOptionsForm when it's clicked.
}

// When the button is clicked, call:
GoogleUmp.ShowPrivacyOptionsForm(result => 
    Debug.Log($"Result -> success:{result.success}, error code:{result.error_code}, error message:{result.error_message}")
);

The ShowPrivacyOptionsForm method takes a callback argument of type Action<ConsentResults>. The ConsentResults object returned in the callback contains a success field, which indicates whether the displying privacy options form was successful. If success is false, you can check the error_code and error_message fields in ConsentResults to get details about the error that occurred.

Full example

This example shows the UMP flow. If you also use ATT on iOS, route the guarded InitializeAds() step through your ATT completion callback before calling Ad.Initialize.

In order to gain a better understanding of the flow of updating consent data and gathering the user's consent, take a look at the following piece of code:

// On App Launch
public void OnStartup() {
    GoogleUmp.RequestConsentInfoUpdate(infoUpdateResult => {
        if (infoUpdateResult.success) {
            GoogleUmp.LoadAndShowConsentFormIfRequired(loadAndShowResult => {
                // Consent has been gathered

                if (GoogleUmp.IsPrivacyOptionsRequired()) {
                    // Generate a button in options menu which calls ShowPrivacyOptionsForm method
                }

                if (GoogleUmp.CanRequestAds())
                    InitializeAds();
            });
        }
        else if (GoogleUmp.CanRequestAds()) {
            InitializeAds();
        }
    });

    // Check if you can initialize Ads in parallel
    if (GoogleUmp.CanRequestAds())
        InitializeAds();
}

private bool isAdsInitializeCalled = false;

private void InitializeAds() 
{
    if (!isAdsInitializeCalled) {
        // Initialize ads
        isAdsInitializeCalled = true;
    }
}

Testing

If you want to test the integration in your app as you're developing, follow these steps to programmatically register your test device. Be sure to remove the code that sets these test device IDs before you release your app.

Call RequestConsentInfoUpdate
Check the log output for a message similar to the following example, which shows your device ID inside the quotations:

Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("<YOUR_TEST_DEVICE_ID>") to set this as a debug device.

Copy your test device ID to your clipboard.
Modify your code to pass testDeviceHashedId parameter in the RequestConsentInfoUpdate method

GoogleUmp.RequestConsentInfoUpdate(callback: result => {}, testDeviceHashedId: "TEST-DEVICE-HASHED-ID");

Force a geography

Plankton's UMP feature allows you to test your app's behavior as if the device were located in different regions by using the debugGeography parameter in the RequestConsentInfoUpdate method.

GoogleUmp.DebugGeography.Disabled: Uses the actual device location.
GoogleUmp.DebugGeography.Eea: Simulates a location under GDPR regulations (European Economic Area).
GoogleUmp.DebugGeography.Other: Simulates a location outside of GDPR regulations.

You can set your testDeviceHashedId and manually specify the geography for testing:

GoogleUmp.RequestConsentInfoUpdate(
    callback: result => {},
    debugGeography: GoogleUmp.DebugGeography.Eea,
    testDeviceHashedId: "TEST-DEVICE-HASHED-ID"
);

note

Debug settings only work on test devices.

In testing your app with the UMP SDK, you might find it helpful to reset the state of the SDK so that you can simulate a user's first install experience. The following method provides a way for you to accomplish this:

GoogleUmp.ResetConsentInformation();

API References

Defined Types

GoogleUmp.DebugGeography

Value	Description
Disabled	Uses the actual location; default for production.
Eea	Simulates the European Economic Area on a registered test device.
Other	Simulates a location outside the EEA on a registered test device.

In this section, we will discuss the classes associated with this feature:

Classes

ConsentResults

Field Name	Field Type	Default Value	Field Description
success	bool	false	A flag indicating if the process was successful or not
error_code	int	0	The error code returned by UMP SDK
error_message	string	string.Empty	The error message returned by UMP SDK, explaining the reason of failure

Method Summaries

Method	Arguments	Return Type
RequestConsentInfoUpdate	System.Action<ConsentResults> callback,DebugGeography debugGeography = DebugGeography.Disabled, string testDeviceHashedId = "", bool tagForUnderAgeOfConsent = false	void
LoadAndShowConsentFormIfRequired	System.Action<ConsentResults> callback	void
ShowPrivacyOptionsForm	System.Action<ConsentResults> callback	void
CanRequestAds	(no arguments)	bool
IsPrivacyOptionsRequired	(no arguments)	bool
ResetConsentInformation	(no arguments)	void

Methods Details

In this section you'll find detailed information on each method of GoogleUmp feature of Plankton.

RequestConsentInfoUpdate

Arguments

Field	Type	Description
callback	System.Action<ConsentResults>	If the `success` field of ConsentResults is true, it means that you can load and show the consent form. If it's false, it means that the consent gathering has failed and you can see the details of error in the `error_code` and `error_message` fields.
debugGeography	GoogleUmp.DebugGeography	Disabled uses the actual location; Eea and Other simulate a region on registered test devices.
tagForUnderAgeOfConsent	bool	Set tagForUnderAgeOfConsent to indicate whether a user is under the age of consent. Users under the age of consent won't be presented with a GDPR message form.
testDeviceHashedId	string	After requesting a consent update, check the log output for a message that looks like the one below, which shows you your device ID: Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("TEST") to set this as a debug device. You should copy this id and set it as testDeviceHashedId.

LoadAndShowConsentFormIfRequired

Arguments

Field	Type	Description
callback	System.Action<ConsentResults>	If the `success` field of ConsentResults is true, the consent form has been shown at least once or the user is not in the GDPR region and there is no need to show the consent form. If it's false, it means that showing the consent form has failed and you can see the details of error in the `error_code` and `error_message` fields.

ShowPrivacyOptionsForm

Arguments

Field	Type	Description
callback	System.Action<ConsentResults>	If the `success` field of ConsentResults is true, it means that the consent form has been shown. If it's false, it means that showing the consent form has failed and you can see the details of error in the `error_code` and `error_message` fields.

Introduction​

Before you begin​

Prerequisites​

Create a message type​

Implementation​

Request for consent information​

Load and show a consent form if required​

Request ads​

Privacy options​

Full example​

Testing​

Force a geography​

Reset consent state​

API References​

Defined Types​

GoogleUmp.DebugGeography​

Classes​

ConsentResults​

Method Summaries​

Methods Details​

RequestConsentInfoUpdate​

Arguments​

LoadAndShowConsentFormIfRequired​

Arguments​

ShowPrivacyOptionsForm​

Arguments​

Introduction

Before you begin

Prerequisites

Create a message type

Implementation

Request for consent information

Load and show a consent form if required

Request ads

Privacy options

Full example

Testing

Force a geography

Reset consent state

API References

Defined Types

GoogleUmp.DebugGeography

Classes

ConsentResults

Method Summaries

Methods Details

RequestConsentInfoUpdate

Arguments

LoadAndShowConsentFormIfRequired

Arguments

ShowPrivacyOptionsForm

Arguments