Get started

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>

Gather consent

To gather consent, complete the following steps:

1. Request for the most recent user consent information.
2. Load and present a consent form, if required.

Request for consent information

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.

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

Load and present a privacy message form if required

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.

Key Point: If no privacy message forms require collection of user consent prior to requesting ads, the callback is invoked immediately.

The following code demonstrates how to request the user's latest consent information. If required, the code loads and presents a privacy message form:

Java

// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
    activity,
    params,
    () ->
        UserMessagingPlatform.loadAndShowConsentFormIfRequired(
            activity, onConsentGatheringCompleteListener::consentGatheringComplete),
    onConsentGatheringCompleteListener::consentGatheringComplete);
ConsentManager.java

Kotlin

// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
  activity,
  params,
  {
    UserMessagingPlatform.loadAndShowConsentFormIfRequired(activity) { formError ->
      // Consent has been gathered.
      onConsentGatheringCompleteListener.consentGatheringComplete(formError)
    }
  },
  { requestConsentError ->
    onConsentGatheringCompleteListener.consentGatheringComplete(requestConsentError)
  },
)

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 ConsentInformation.PrivacyOptionsRequirementStatus to determine if a privacy options entry point is required for your app:

Java

/** Helper function to determine if a privacy options entry point is required. */
public boolean isPrivacyOptionsRequired() {
  return consentInformation.getPrivacyOptionsRequirementStatus()
      == PrivacyOptionsRequirementStatus.REQUIRED;
}
ConsentManager.java

Kotlin

/** Helper variable to determine if the privacy options form is required. */
val isPrivacyOptionsRequired: Boolean
  get() =
    consentInformation.privacyOptionsRequirementStatus ==
      ConsentInformation.PrivacyOptionsRequirementStatus.REQUIRED

Add a visible element to your app

If a privacy 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

// Check ConsentInformation.getPrivacyOptionsRequirementStatus() to see the button should
// be shown or hidden.
if (consentManager.isPrivacyOptionsRequired()) {
  privacyButton.setVisibility(View.VISIBLE);
}
MyActivity.java

Kotlin

// Check ConsentInformation.getPrivacyOptionsRequirementStatus() to see the button should
// be shown or hidden.
if (consentManager.isPrivacyOptionsRequired) {
  privacyButton.visibility = View.VISIBLE
}

Present the privacy options form

When the user interacts with your element, present the privacy options form:

Java

UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener);
ConsentManager.java

Kotlin

UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)

Request ads

Before requesting ads in your app, check if you have obtained consent from the user using canRequestAds(). There are two places to check while gathering consent:

• After consent has been gathered in the current session.
• 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.

Note: canRequestAds() always returns false until you have called requestConsentInfoUpdate()

If an error occurs during the consent gathering process, you should still check if you can request ads. The UMP SDK uses the consent status from the previous session.

The following code checks if you can request ads during the consent gathering process:

Java

consentManager.gatherConsent(
    consentError -> {
      if (consentError != null) {
        // Consent not obtained in current session.
        Log.i(
            LOGTAG,
            "Consent Error: "
                + String.format(
                    "%s: %s", consentError.getErrorCode(), consentError.getMessage()));
      }

      if (consentManager.canRequestAds()) {
        initializeImaSdk();
      } else {
        Log.i(LOGTAG, "Consent not available to request ads");
      }
      // ...
    });

// This sample attempts to load ads using consent obtained in the previous session.
if (consentManager.canRequestAds()) {
  initializeImaSdk();
}
MyActivity.java

Kotlin

consentManager.gatherConsent(this) { error ->
  if (error != null) {
    // Consent not obtained in current session.
    Log.d(LOGTAG, "${error.errorCode}: ${error.message}")
  }
  if (consentManager.canRequestAds) {
    initializeImaSdk()
  } else {
    Log.i(LOGTAG, "Consent not available to request ads")
  }
  // ...
}
// This sample attempts to load ads using consent obtained in the previous session.
if (consentManager.canRequestAds) {
  initializeImaSdk()
}

The following code sets up the IMA DAI SDK after the user's consent is gathered:

Java

private void initializeImaSdk() {
  if (sdkFactory != null) {
    // If the SDK is already initialized, do nothing.
    return;
  }

  sdkFactory = ImaSdkFactory.getInstance();

  adDisplayContainer =
      ImaSdkFactory.createAdDisplayContainer(videoPlayerContainer, videoAdPlayerAdapter);

  createAdsLoader();
  setUpPlayButton();
}
MyActivity.java

Kotlin

private fun initializeImaSdk() {
  sdkFactory = ImaSdkFactory.getInstance()
  adDisplayContainer = ImaSdkFactory.createAdDisplayContainer(videoPlayerContainer, videoAdPlayerAdapter)
  createAdsLoader()
  setUpPlayButton()
}

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.

Note: As of version 2.2.0, emulators don't need to be added to your device ID list as they are test devices by default.

1. Call requestConsentInfoUpdate().

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

3. Copy your test device ID to your clipboard.

4. 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()

Caution: This method is intended to be used for testing purposes only. You shouldn't call reset() in production code.

Examples on GitHub

See a full example of the UMP SDK integration covered in this page in UmpExample.