此页面由 Cloud Translation API 翻译。

开始使用

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

前提条件

Android API 级别 21 或更高级别

创建消息类型

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

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

使用 Gradle 进行安装

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

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

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

添加应用 ID

您可以在 AdMob 界面中找到您的应用 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>

征求用户意见

如需征求用户同意，请完成以下步骤：

请求获取最新的用户意见征求信息。
根据需要加载并显示用户意见征求表单。

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

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

根据需要加载和显示隐私权消息表单

收到最新的意见征求状态后，调用 loadAndShowConsentFormIfRequired() 以加载收集用户意见征求所需的所有表单。加载后，表单会立即显示。

以下代码演示了如何请求用户的最新意见征求信息。如有需要，该代码会加载并显示隐私权消息表单：

Java


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

向应用添加可见元素

如果需要隐私权入口点，请向应用添加一个可见且可交互的界面元素，用于显示隐私权选项表单。如果不需要隐私权入口点，请将界面元素配置为不可见且不可互动。

Java


if (googleMobileAdsConsentManager.isPrivacyOptionsRequired()) {
  // Regenerate the options menu to include a privacy setting.
  invalidateOptionsMenu();
}MyActivity.java

Kotlin


if (googleMobileAdsConsentManager.isPrivacyOptionsRequired) {
  // Regenerate the options menu to include a privacy setting.
  invalidateOptionsMenu()
}MainActivity.kt

显示隐私选项表单

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

Java


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

Kotlin


UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)GoogleMobileAdsConsentManager.kt

提出广告请求

在应用中请求展示广告之前，请检查您是否已使用 canRequestAds() 征得用户同意。在征求用户意见时，您可以检查以下两个位置：

在当前会话中征得用户同意后。
在调用 requestConsentInfoUpdate() 后立即调用。系统可能已在上一会话中征得用户同意。延迟时间最佳实践：我们建议您不要等待回调完成，以便在应用启动后尽快开始加载广告。

如果在征求用户同意的过程中发生错误，您仍应检查自己是否可以请求展示广告。UMP SDK 会使用上一个会话中的意见征求状态。

以下代码会检查您是否可以在征求用户意见的过程中请求展示广告：

Java


googleMobileAdsConsentManager.gatherConsent(
    this,
    consentError -> {
      if (consentError != null) {
        // Consent not obtained in current session.
        Log.w(
            TAG,
            String.format("%s: %s", consentError.getErrorCode(), consentError.getMessage()));
      }

      if (googleMobileAdsConsentManager.canRequestAds()) {
        initializeMobileAdsSdk();
      }
      // ...
    });

// This sample attempts to load ads using consent obtained in the previous session.
if (googleMobileAdsConsentManager.canRequestAds()) {
  initializeMobileAdsSdk();
}

Kotlin


googleMobileAdsConsentManager.gatherConsent(this) { error ->
  if (error != null) {
    // Consent not obtained in current session.
    Log.d(TAG, "${error.errorCode}: ${error.message}")
  }

  if (googleMobileAdsConsentManager.canRequestAds) {
    initializeMobileAdsSdk()
  }
  // ...
}

// This sample attempts to load ads using consent obtained in the previous session.
if (googleMobileAdsConsentManager.canRequestAds) {
  initializeMobileAdsSdk()
}

以下代码会在征得用户同意后设置 Google 移动广告 SDK：

Java


private void initializeMobileAdsSdk() {
  if (isMobileAdsInitializeCalled.getAndSet(true)) {
    return;
  }
  new Thread(
          () -> {
            // Initialize the Google Mobile Ads SDK on a background thread.
            MobileAds.initialize(this, initializationStatus -> {});

            // Load an ad on the main thread.
            runOnUiThread(this::loadBanner);
          })
      .start();
}
MyActivity.java

Kotlin


private fun initializeMobileAdsSdk() {
  if (isMobileAdsInitializeCalled.getAndSet(true)) {
    return
  }
  CoroutineScope(Dispatchers.IO).launch {
    // Initialize the Google Mobile Ads SDK on a background thread.
    MobileAds.initialize(this@MainActivity) {}

    runOnUiThread {
      // Load an ad on the main thread.
      loadBanner()
    }
  }
}
MainActivity.kt

测试

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

欢迎致电requestConsentInfoUpdate()。
检查日志输出，以查找类似于以下示例的消息（向您显示您的设备 ID 以及如何将设备添加为测试设备）：
```
Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("33BE2250B43518CCDA7DE426D04EE231") to set this as a debug device.
```
将测试设备 ID 复制到剪贴板。

修改代码，以便调用 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 提供了一种方法：使用 setDebugGeography() 测试您的应用行为，就像设备位于欧洲经济区 (EEA) 或英国境内一样。请注意，调试设置仅适用于测试设备。

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。

开始使用

前提条件

创建消息类型

使用 Gradle 进行安装

添加应用 ID

征求用户意见

请求提供意见征求信息

根据需要加载和显示隐私权消息表单

Java

Kotlin

隐私选项

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

Java

Kotlin

向应用添加可见元素

Java

Kotlin

显示隐私选项表单

Java

Kotlin

提出广告请求

Java

Kotlin

Java

Kotlin

测试

Java

Kotlin

强制调试地理位置

Java

Kotlin

重置用户同意情况

Java

Kotlin

GitHub 上的示例