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 Target API Level to 33 or higher
  • Set Minimum Api Level to 21 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;

Request for consent information

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

Load and show a consent form if required

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<ConsentResult>. The ConsentResult 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 ConsentResult 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:

1. Once consent has been gathered in the current session (in the callback of LoadAndShowConsentFormIfRequired).

2. 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)
    Plankton.Ad.Initialize(...)

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

CanRequestAds always returns false until you have called requestConsentInfoUpdate()

warning

If you don't add GoogleUmp in Plankton settings but you call this method in your code, you will get a runtime exception telling you that UMP dependency is missing. This is to protect you from violating Google Play regulations.

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:

1. Implement a UI element, such as a button in your game's settings page, that can trigger a privacy options form.

2. Once LoadAndShowConsentFormIfRequired completes, call IsPrivacyOptionsRequired to determine whether to display the UI element that can present the privacy options form.

3. 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<ConsentResult>. The ConsentResult 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 ConsentResult to get details about the error that occurred.

Full example

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

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

1. Call RequestConsentInfoUpdate
2. 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("33BE2250B43518CCDA7DE426D04EE231") to set this as a debug device.

3. Copy your test device ID to your clipboard.
4. 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 provides a way to test your app's behavior as though the device was located in the EEA or UK using the setDebugGeography parameter in the RequestConsentInfoUpdate method. Note that debug settings only work on test devices.

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

Reset consent state

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 Refrences

---

Defined Types

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

Classes

ConsentResult

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,bool setDebugGeography = false, bool setTagForUnderAgeOfConsent = false,string testDeviceHashedId = ""	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 ConsentResult 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.
setDebugGeography	bool	To test UMP, set setDebugGeography to True (if you don't set it, its default value is false)
setTagForUnderAgeOfConsent	bool	Set setTagForUnderAgeOfConsent 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 setting setDebugGeography to true, 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<ConsentResult>	If the success field of ConsentResult 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<ConsentResult>	If the success field of ConsentResult 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.