Google User Messaging Platform (UMP) SDK 是一款隐私权和消息工具,可帮助您管理隐私选项。如需了解详情,请参阅“隐私权和消息”页面简介。 您可以在 UMP 示例应用中查看使用 UMP SDK 的有效 IMA 实现。
前提条件
- Android API 级别 21 或更高级别
创建消息类型
在 Ad Manager 账号的隐私权和消息标签页下,使用其中一种可用的用户消息类型创建用户消息。UMP SDK 会尝试显示根据您在项目中设置的互动式媒体广告应用 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
您可以在 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.
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.
},
)
加载并显示隐私权消息表单
收到最新的意见征求状态后,调用
loadAndShowConsentFormIfRequired()
以加载收集用户意见所需的所有表单。加载后,表单会立即显示。
Java
UserMessagingPlatform.loadAndShowConsentFormIfRequired(
activity,
formError -> {
// Consent gathering process is complete.
});
Kotlin
UserMessagingPlatform.loadAndShowConsentFormIfRequired(activity) { formError ->
// Consent has been gathered.
}
隐私选项
某些隐私权消息表单会通过发布商呈现的隐私权选项入口点显示,以便用户随时管理其隐私权选项。如需详细了解您的用户会在隐私权选项入口点看到哪条消息,请参阅可用的用户消息类型。
检查是否需要隐私选项入口点
调用
requestConsentInfoUpdate()
后,请检查
getPrivacyOptionsRequirementStatus()
,以确定您的应用是否需要隐私选项入口点。如果需要入口点,请向应用添加一个可见且可互动的界面元素,以显示隐私选项表单。如果不需要隐私权入口点,请将界面元素配置为不可见且不可互动。
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
如需查看隐私权选项要求状态的完整列表,请参阅
ConsentInformation.PrivacyOptionsRequirementStatus
。
显示隐私选项表单
当用户与您的元素互动时,显示隐私选项表单:
Java
UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener);
Kotlin
UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)
在征得用户同意后请求展示广告
在请求展示广告之前,请使用
canRequestAds()
检查您是否已征得用户同意:
Java
consentInformation.canRequestAds();
Kotlin
consentInformation.canRequestAds()
您可以查看以下位置,了解自己是否可以在征求用户意见时请求展示广告:
- UMP SDK 在当前会话中收集用户意见后。
- 在调用
requestConsentInfoUpdate()
后立即调用。UMP SDK 可能已在上一应用会话中征得用户同意。
如果在征求用户意见的过程中出现错误,请检查您是否可以请求展示广告。UMP SDK 会使用上一个应用会话中的意见征求状态。
防止重复的广告请求工作
在征得用户同意后以及调用
requestConsentInfoUpdate()
后,请检查
canRequestAds()
,确保您的逻辑可防止发出多余的广告请求,这可能会导致这两次检查都返回 true
。例如,使用布尔值变量。
测试
如果您希望在应用开发过程中测试集成,请按照以下步骤以编程方式注册您的测试设备。在发布应用之前,请务必移除用于设置这些测试设备 ID 的代码。
- 欢迎致电
requestConsentInfoUpdate()
。 检查日志输出,以查找类似于以下示例的消息(向您显示您的设备 ID 以及如何将设备添加为测试设备):
Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("33BE2250B43518CCDA7DE426D04EE231") to set this as a debug device.
将测试设备 ID 复制到剪贴板。
修改代码,以便调用
ConsentDebugSettings.Builder().addTestDeviceHashedId()
并将其传入您的测试设备 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 提供了一种方法:使用 DebugGeography
测试您的应用行为,就像设备位于欧洲经济区 (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 集成的完整示例,请参阅 UmpExample。