设置 UMP SDK

请选择平台： Android（Beta 版） 新 Android iOS Unity Flutter

Google User Messaging Platform (UMP) SDK 是一款隐私权和消息工具，可帮助您管理隐私权选择。如需了解详情，请参阅 隐私权和消息简介。

前提条件

  • Android API 级别 21 或更高级别

创建消息类型

在 Ad Manager 账号的隐私权和消息 标签页下，使用其中一种可用的用户消息类型创建用户消息。UMP SDK 会尝试显示根据项目中设置的 Ad Manager 应用 ID 创建的隐私权消息。

如需了解详情，请参阅 隐私权和消息简介。

通过 Gradle 安装

将 Google User Messaging Platform SDK 的依赖项添加到模块的 应用级 Gradle 文件（通常为 app/build.gradle）中：

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

更改应用的 build.gradle 后，请务必使用 Gradle 文件将项目同步。

添加应用 ID

您可以在 Ad Manager 界面中找到您的应用 ID。 使用以下代码段将该 ID 添加到您的 AndroidManifest.xml 中：

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

如需获取用户的意见征求信息，请执行以下操作：

声明一个 ConsentInformation 实例：

Java

private final ConsentInformation consentInformation;

Kotlin

private lateinit val consentInformation: ConsentInformation

初始化 ConsentInformation 实例：

Java

consentInformation = UserMessagingPlatform.getConsentInformation(context);

Kotlin

consentInformation = UserMessagingPlatform.getConsentInformation(context)

每次启动应用时，您都应使用 requestConsentInfoUpdate() 请求更新用户的意见征求信息。此请求会检查以下内容：

  • 是否需要征求用户意见 。例如，首次需要征求用户意见，或者之前的意见征求决定已过期。
  • 是否需要隐私设置选项入口点 。某些隐私权消息要求应用允许用户随时修改其隐私设置选项。

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.
GoogleMobileAdsConsentManager.java

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.
  },
)
GoogleMobileAdsConsentManager.kt

加载并显示隐私权消息表单

收到最新的同意情况后，调用 loadAndShowConsentFormIfRequired() 以加载收集用户同意所需的任何表单。加载后，表单会立即显示。

Java


UserMessagingPlatform.loadAndShowConsentFormIfRequired(
    activity,
    formError -> {
      // Consent gathering process is complete.
    });
GoogleMobileAdsConsentManager.java

Kotlin


UserMessagingPlatform.loadAndShowConsentFormIfRequired(activity) { formError ->
  // Consent gathering process is complete.
}
GoogleMobileAdsConsentManager.kt

隐私设置选项

某些隐私权消息表单是从发布商呈现的隐私设置选项入口点显示的，让用户可以随时管理其隐私设置选项。 如需详细了解用户在隐私设置选项 入口点看到的消息，请参阅 可用的用户消息类型。

检查是否需要隐私设置选项入口点

调用 requestConsentInfoUpdate() 后，检查 getPrivacyOptionsRequirementStatus() 以 确定您的应用是否需要隐私设置选项入口点。如果需要入口 点，请向应用添加一个可见且可交互的界面元素，以 显示隐私设置选项表单。如果不需要隐私设置选项入口点，请将界面元素配置为不可见且不可交互。

Java


/** Helper variable to determine if the privacy options form is required. */
public boolean isPrivacyOptionsRequired() {
  return consentInformation.getPrivacyOptionsRequirementStatus()
      == PrivacyOptionsRequirementStatus.REQUIRED;
}

GoogleMobileAdsConsentManager.java

Kotlin


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

GoogleMobileAdsConsentManager.kt

如需查看隐私设置选项要求状态的完整列表，请参阅 ConsentInformation.PrivacyOptionsRequirementStatus。

显示隐私设置选项表单

当用户与您的元素互动时，显示隐私设置选项表单：

Java


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

Kotlin


UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)
GoogleMobileAdsConsentManager.kt

在征得用户同意后请求广告

在请求广告之前，使用 canRequestAds() 检查您是否已 征得用户同意：

Java

consentInformation.canRequestAds();

Kotlin

consentInformation.canRequestAds()

以下列出了在收集用户意见时检查是否可以请求广告的位置：

  • 在 UMP SDK 在当前会话中收集用户意见后。
  • 在您调用 requestConsentInfoUpdate() 后立即执行。UMP SDK 可能已在之前的应用会话中征得用户同意。
之前， canRequestAds() 始终返回 false

如果在收集用户意见的过程中发生错误，请检查是否可以请求广告。UMP SDK 使用的是之前应用会话中的同意情况。

避免重复的广告请求工作

在收集用户意见后以及在调用 requestConsentInfoUpdate()后检查 canRequestAds()时，请确保您的逻辑可以防止重复的广告请求，以免这两个检查都返回true。例如，使用布尔变量。

测试

如果您希望在应用开发过程中测试集成，请按照以下步骤以程序化方式注册您的测试设备。在发布应用之前，请务必移除用于设置这些测试设备 ID 的代码。

  1. 调用 requestConsentInfoUpdate()。

  2. 检查日志输出，以查找类似于以下示例的消息，其中会显示您的设备 ID 以及如何将设备添加为测试设备：

    Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("33BE2250B43518CCDA7DE426D04EE231") to set this as a debug device.

  3. 将测试设备 ID 复制到剪贴板。

  4. 修改代码，以便调用 ConsentDebugSettings.Builder().TestDeviceHashedIds 并传入 您的测试设备 ID 列表。

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

强制调试地理位置

UMP SDK 提供了一种方法：测试您的应用行为，就像设备 位于欧洲经济区 (EEA)、 英国 (UK) 和瑞士等各种区域一样，使用 DebugGeography。请注意，调试设置仅适用于测试设备。

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,
    ...
)

通过 UMP SDK 测试应用时，您可能会发现重置 SDK 的状态很实用，因为您可以模拟用户的首次安装体验。 SDK 提供了 reset() 方法来执行此操作。

Java

consentInformation.reset();

Kotlin

consentInformation.reset()

GitHub 上的示例

如需查看本页中介绍的 UMP SDK 集成的完整示例，请参阅 Java BannerExample 和 Kotlin BannerExample。