开始

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>

如需征求用户意见,请完成以下步骤:

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

您应在每次启动应用时使用 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));

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

隐私设置选项

某些隐私权消息表单从发布商呈现的隐私权选项入口点呈现,让用户能够随时管理自己的隐私权选项。如需详细了解您的用户会在隐私权选项入口点看到哪条消息,请参阅可用的用户消息类型

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

调用 requestConsentInfoUpdate() 后,请检查 getPrivacyOptionsRequirementStatus(),以确定您的应用是否需要隐私选项入口点:

Java


/** Helper variable to determine if the privacy options form 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

向应用添加可见元素

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

Java


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

Kotlin


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

显示隐私选项表单

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

Java


UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener);

Kotlin


UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)

提出广告请求

在您的应用中请求广告之前,请检查您是否已使用 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();
}

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()
    }
  }
}

测试

如果您希望在开发过程中测试应用中的集成,请按照以下步骤以编程方式注册测试设备。在发布应用之前,请务必移除用于设置这些测试设备 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 提供了一种方法来使用 setDebugGeography() 测试应用行为,就像设备位于不同区域(例如欧洲经济区或英国)一样。请注意,调试设置仅适用于测试设备。

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 BannerExampleKotlin BannerExample