Google UMP

1. Background

Starting January 16, 2024, publishers and developers using Google AdSense, Ad Manager, or AdMob to serve ads to users in the European Economic Area or the United Kingdom must use a Consent Management Platform (CMP) that is certified by Google and integrated with IAB's Transparency and Consent Framework (TCF).

Starting from SDK version 6.2.87, the TopOn SDK provides a method compatible with the UMP SDK to configure the GDPR level. The TopOn SDK internally uses this level to configure the GDPR reporting level for third-party ad networks.

2. UMP Usage Process

2.1 Enable UMP in the AdMob Console

① Visit the AdMob Console, log in to your AdMob account — Add your app in AdMob (if you have not added the app yet).
② Click "Privacy & messaging".
③ Click "European regulations - Manage".
④ Click "Create message" and wait for the GDPR message page to open.
⑤ On the GDPR message page, click "Select apps" in the top right corner and select the app for which you want to display the GDPR message.
⑥ Select the language in which you want to display the message.
⑦ In the "Targeting" section, select the "Countries subject to GDPR (EEA and UK)" option.

The following configuration can improve the probability of users consenting to GDPR:
① Under "User options - Close (do not consent)", select Close.
② Style adjustment: Select the "Style" section

• Under the button section, adjust the "Secondary color" to white (#ffffff).
• Under the button section, adjust the "Secondary font color" to gray (#6e6e6e).

The overall effect after adjustment is shown in the image below. Finally, click "Publish" in the top right corner.

2.2 Self-Specified Ad Partners

Note: By default, Google may not display all ad networks integrated in your project in your GDPR message. Failure to include these ad networks may adversely affect your ad revenue. Please follow the steps in this section to ensure that all ad networks integrated in your project appear in the GDPR message.

Customize which ad partners are displayed in the GDPR message:

(1) In the AdMob console, under "Privacy & messaging", click "GDPR Settings" to open the GDPR settings.

(2) Click the edit icon () under the "Review your ad partners" section.

(3) Refer to the table below and check all ad networks integrated in your project.

Tips: For ad networks not listed in this table, such as Pangle, Maio, Appnext, MyTarget, Yandex, Helium, etc., since they are not in the AdMob GDPR ad partner list, TopOn will internally use the popup consent result to set the GDPR reporting level for these ad networks.

(4) Click "Confirm".

(5) Click the "Save" button at the bottom of the GDPR settings page.

Note: If a popup asking "Re-consent all eligible users?" appears, select "Re-prompt".

2.3 Enable UMP in the Project

(1) First, add the Google User Messaging Platform SDK dependency to the module's app-level Gradle file (usually app/build.gradle).

dependencies {
    implementation("com.google.android.ump:user-messaging-platform:3.1.0")
}

(2) Add gms.ads.APPLICATION_ID in AndroidManifest.xml, with the value being the app ID created in the AdMob console.

<manifest>
    <application>
        <meta-data
            android:name="com.google.android.gms.ads.APPLICATION_ID"
            android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"/>
    </application>
</manifest>

(3) Add the following configuration to the obfuscation configuration file proguard-android.txt:

-keep public class com.google.android.ump.*

ATSDK.showGDPRConsentDialog(activity, new ATGDPRConsentDismissListener() {
    @Override
    public void onDismiss(ConsentDismissInfo consentDismissInfo) {
        // Note: SDK initialization must be performed in this callback, and ads must be loaded after initialization.
        ATSDK.init(activity, appId, appKey);
    }
},"appId");

/**
 * deviceId: Obtain by calling ATSDK.showGDPRConsentDialog and filtering the keyword "addTestDeviceHashedId" in logcat.
 */
ATSDK.setDebuggerConfig(activity, "", 
        new ATDebuggerConfig.Builder().setUMPTestDeviceId("deviceid").build());

TUSDK.showGDPRConsentDialog(activity, new TUGDPRConsentDismissListener() {
    @Override
    public void onDismiss(ConsentDismissInfo consentDismissInfo) {
        // Note: SDK initialization must be performed in this callback, and ads must be loaded after initialization.
        TUSDK.init(activity, appId, appKey);
    }
},"appId");

/**
 * deviceId: Obtain by calling TUSDK.showGDPRConsentDialog and filtering the keyword "addTestDeviceHashedId" in logcat.
 */
TUSDK.setDebuggerConfig(activity, "", 
        new TUDebuggerConfig.Builder().setUMPTestDeviceId("deviceid").build());

2.4 Add a Link in the App to Allow Users to Withdraw Consent

Version 6.5.50 added the showGDPRConsentSecondDialog method to allow modification of the consent solicitation process, enabling a second GDPR selection.

ATSDK.showGDPRConsentSecondDialog(activity, new ATGDPRConsentDismissListener() {
    @Override
    public void onDismiss(ConsentDismissInfo consentDismissInfo) {
        // Note: SDK initialization must be performed in this callback, and ads must be loaded after initialization.
        ATSDK.init(activity, appId, appKey);
    }
},"appId");

TUSDK.showGDPRConsentSecondDialog(activity, new TUGDPRConsentDismissListener() {
    @Override
    public void onDismiss(ConsentDismissInfo consentDismissInfo) {
        // Note: SDK initialization must be performed in this callback, and ads must be loaded after initialization.
        TUSDK.init(activity, appId, appKey);
    }
},"appId");

Note: Withdrawing consent is the process by which users in the European Economic Area (EEA), the United Kingdom, and Switzerland can withdraw their consent after having consented to personalized ads. A corresponding link must be provided in the app's menu to allow users who wish to withdraw their consent to do so, and then the user consent message will be shown to them again.

For details, please refer to here.

Please refer to the Google AdMob Ads SDK Developer Documentation to implement the privacy settings option.

3. FAQ

(1) The UMP SDK is already integrated in the project. How to handle updating TopOn to version 6.2.87 or above?

Since the TopOn SDK will prioritize reading the GDPR-related settings configured by the UMP SDK during initialization to set the GDPR reporting level for third-party ad networks, developers need to ensure that the "Ad Partners" list in the AdMob console GDPR settings includes all ad networks integrated in your app (excluding Pangle, Huawei, Maio, Appnext, MyTarget, Yandex, and Helium platforms). Refer to Self-Specified Ad Partners above for configuration.
In addition, it is recommended to use the TopOn SDK's showGDPRConsentDialog to replace the original UMP SDK API call code. Refer to the sample code above and perform SDK initialization in the onDismiss callback. If you wish to retain the original UMP SDK API call logic in the project, you need to refer to the example in the AdMob UMP Usage Guide, and initialize the TopOn SDK in the OnConsentFormDismissedListener#onConsentFormDismissed() callback or after determining that consentInformation.canRequestAds is true.

(2) The project already has UMP SDK integrated, but later the app update removed the UMP SDK usage. How to handle updating TopOn to version 6.2.87 or above?

Since the TopOn SDK will prioritize reading the GDPR-related settings set by the UMP SDK during initialization, even if the UMP SDK is removed, the old GDPR configuration cache files still remain locally. Developers need to call the following code to remove the cached data when removing the UMP SDK version. Sample code is as follows:
Note: After removing the UMP SDK GDPR local cache using this method, it may affect AdMob's ability to serve ads to users in the EEA or UK.

SharedPreferences sharedPreferences = PreferenceManager.getDefaultSharedPreferences(context);
SharedPreferences.Editor editor = sharedPreferences.edit();
editor.remove("IABTCF_TCString");
editor.remove("IABTCF_AddtlConsent");
editor.remove("IABTCF_VendorConsents");
editor.remove("IABTCF_PurposeConsents");
editor.commit();