The Google User Messaging Platform (UMP) SDK is a privacy and messaging tool to help you manage privacy choices. For more information, see About Privacy & messaging. You can see a working IMA implementation with the UMP SDK in the UMP sample app.
Prerequisites
- Android API level 21 or higher
Create a message type
Create user messages with one of the Available user message types under the Privacy & messaging tab of your Ad Manager account. The UMP SDK attempts to display a privacy message created from the Interactive Media Ads Application ID set in your project.
For more details, see About privacy and messaging.
Install with Gradle
Add the dependency for the Google User Messaging Platform SDK to your module's
app-level Gradle file, normally app/build.gradle
:
dependencies {
implementation("com.google.android.ump:user-messaging-platform:3.1.0")
}
After making the changes to your app's build.gradle
, be sure to sync your
project with Gradle files.
Add the application ID
You can find your application ID in the
Ad Manager UI.
Add the ID to your
AndroidManifest.xml
with the following code snippet:
<manifest>
<application>
<meta-data
android:name="com.google.android.gms.ads.APPLICATION_ID"
android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"/>
</application>
</manifest>
Get the user's consent information
To get the user's consent information, do the following:
Declare an instance of ConsentInformation
:
Java
private final ConsentInformation consentInformation;
Kotlin
private lateinit val consentInformation: ConsentInformation
Initialize the ConsentInformation
instance:
Java
consentInformation = UserMessagingPlatform.getConsentInformation(context);
Kotlin
consentInformation = UserMessagingPlatform.getConsentInformation(context)
You should request an update of the user's consent information at every app
launch, using
requestConsentInfoUpdate()
. This request checks the following:
- Whether consent is required. For example, consent is required for the first time, or the previous consent decision expired.
- Whether a privacy options entry point is required. Some privacy messages require apps to allow users to modify their privacy options at any time.
Java
// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
activity,
params,
() -> // Called when consent information is successfully updated.
requestConsentError -> // Called when there's an error updating consent information.
Kotlin
// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
activity,
params,
{
// Called when consent information is successfully updated.
},
{ requestConsentError ->
// Called when there's an error updating consent information.
},
)
Load and present the privacy message form
After you have received the most up-to-date consent status, call
loadAndShowConsentFormIfRequired()
to load any forms required to
collect user consent. After loading, the forms present immediately.
Java
UserMessagingPlatform.loadAndShowConsentFormIfRequired(
activity,
formError -> {
// Consent gathering process is complete.
});
Kotlin
UserMessagingPlatform.loadAndShowConsentFormIfRequired(activity) { formError ->
// Consent has been gathered.
}
Privacy options
Some privacy message forms are presented from a publisher-rendered privacy options entry point, letting users manage their privacy options at any time. To learn more about which message your users see at the privacy options entry point, see Available user message types.
Check if a privacy options entry point is required
After you have called
requestConsentInfoUpdate()
, check
getPrivacyOptionsRequirementStatus()
to
determine if a privacy options entry point is required for your app. If an entry
point is required, add a visible and interactable UI element to your app that
presents the privacy options form. If a privacy entry point is not required,
configure your UI element to be not visible and interactable.
Java
/** Helper function to determine if a privacy options entry point is required. */
public boolean isPrivacyOptionsRequired() {
return consentInformation.getPrivacyOptionsRequirementStatus()
== PrivacyOptionsRequirementStatus.REQUIRED;
}
Kotlin
/** Helper variable to determine if the privacy options form is required. */
val isPrivacyOptionsRequired: Boolean
get() =
consentInformation.privacyOptionsRequirementStatus ==
ConsentInformation.PrivacyOptionsRequirementStatus.REQUIRED
For the full list of privacy options requirement statuses, see
ConsentInformation.PrivacyOptionsRequirementStatus
.
Present the privacy options form
When the user interacts with your element, present the privacy options form:
Java
UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener);
Kotlin
UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)
Request ads with user consent
Before requesting ads, use
canRequestAds()
to check if you've
obtained consent from the user:
Java
consentInformation.canRequestAds();
Kotlin
consentInformation.canRequestAds()
Listed are the following places to check if you can request ads while gathering consent:
- After the UMP SDK gathers consent in the current session.
- Immediately after you have called
requestConsentInfoUpdate()
. The UMP SDK might have obtained consent in the previous app session.
If an error occurs during the consent gathering process, check if you can request ads. The UMP SDK uses the consent status from the previous app session.
Prevent redundant ad request work
As you check
canRequestAds()
after gathering consent and after calling
requestConsentInfoUpdate()
, ensure your logic prevents redundant ad requests that
might result in both checks returning true
. For example, with a boolean
variable.
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 and how to add it as a test device:
Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("33BE2250B43518CCDA7DE426D04EE231") to set this as a debug device.
Copy your test device ID to your clipboard.
Modify your code to call
ConsentDebugSettings.Builder().addTestDeviceHashedId()
and pass in a list of your test device IDs.Java
ConsentDebugSettings debugSettings = new ConsentDebugSettings.Builder(this) .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID") .build(); ConsentRequestParameters params = new ConsentRequestParameters .Builder() .setConsentDebugSettings(debugSettings) .build(); consentInformation = UserMessagingPlatform.getConsentInformation(this); // Include the ConsentRequestParameters in your consent request. consentInformation.requestConsentInfoUpdate( this, params, // ... );
Kotlin
val debugSettings = ConsentDebugSettings.Builder(this) .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID") .build() val params = ConsentRequestParameters .Builder() .setConsentDebugSettings(debugSettings) .build() consentInformation = UserMessagingPlatform.getConsentInformation(this) // Include the ConsentRequestParameters in your consent request. consentInformation.requestConsentInfoUpdate( this, params, // ... )
Force a geography
The UMP SDK provides a way to test your app's behavior as though the device
were located in various regions, such as the EEA or UK, using
DebugGeography
. Note that debug settings only work on test devices.
Java
ConsentDebugSettings debugSettings = new ConsentDebugSettings.Builder(this)
.setDebugGeography(ConsentDebugSettings.DebugGeography.DEBUG_GEOGRAPHY_EEA)
.addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
.build();
ConsentRequestParameters params = new ConsentRequestParameters
.Builder()
.setConsentDebugSettings(debugSettings)
.build();
consentInformation = UserMessagingPlatform.getConsentInformation(this);
// Include the ConsentRequestParameters in your consent request.
consentInformation.requestConsentInfoUpdate(
this,
params,
...
);
Kotlin
val debugSettings = ConsentDebugSettings.Builder(this)
.setDebugGeography(ConsentDebugSettings.DebugGeography.DEBUG_GEOGRAPHY_EEA)
.addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
.build()
val params = ConsentRequestParameters
.Builder()
.setConsentDebugSettings(debugSettings)
.build()
consentInformation = UserMessagingPlatform.getConsentInformation(this)
// Include the ConsentRequestParameters in your consent request.
consentInformation.requestConsentInfoUpdate(
this,
params,
...
)
Reset consent state
When 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 SDK provides the reset()
method to do this.
Java
consentInformation.reset();
Kotlin
consentInformation.reset()
Examples on GitHub
See a full example of the UMP SDK integration covered in this page in UmpExample.