根据 Google《欧盟地区用户意见征求政策》,您必须向位于欧洲经济区 (EEA) 以及英国境内的用户披露相关信息;在法律有要求的情况下,必须征得他们的同意才能使用 Cookie 或其他本地存储方式;此外,您必须同意他们使用个人数据(例如 AdID)来投放广告。此政策反映了欧盟《电子隐私指令》和《一般数据保护条例》(GDPR) 的要求。
为了帮助发布商履行此政策规定的职责,Google 提供了 User Messaging Platform (UMP) SDK。UMP SDK 已更新,可支持最新的 IAB 标准。所有这些配置现在都可以在“隐私权和消息”中轻松处理。 AdMob
前提条件
- 完成入门指南
- Android API 级别 21 或更高级别
- 如果您正在处理与 GDPR 相关的要求,请参阅IAB 要求对欧盟地区用户意见征求消息的影响
创建消息类型
创建用户消息时,您可以使用 可用的用户消息类型 (在 AdMob 账号的隐私权和消息标签页下)创建用户消息。UMP SDK 会尝试显示通过 AdMob 中设置的应用 ID 创建的用户消息。如果没有为您的应用配置消息,SDK 会返回错误。
如需了解详情,请参阅 隐私权和消息简介。
通过 Gradle 安装
将 Google User Messaging Platform SDK 的依赖项添加到您的模块的应用级 Gradle 文件(通常为 app/build.gradle
):
dependencies {
implementation("com.google.android.ump:user-messaging-platform:2.2.0")
}
对应用的 build.gradle
进行更改后,请务必将项目与 Gradle 文件同步。
征求用户同意
每次启动应用时,您都应使用 requestConsentInfoUpdate()
请求更新用户的意见征求信息。这决定了您的用户是否需要提供用户意见征求结果(如果尚未提供或者用户意见征求结果已过期)。
以下示例展示了如何在 onCreate()
方法中通过 MainActivity
检查状态。
Java
package com.example.myapplication;
import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;
import com.google.android.ump.ConsentInformation;
import com.google.android.ump.ConsentRequestParameters;
import com.google.android.ump.FormError;
import com.google.android.ump.UserMessagingPlatform;
public class MainActivity extends AppCompatActivity {
private ConsentInformation consentInformation;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
// Create a ConsentRequestParameters object.
ConsentRequestParameters params = new ConsentRequestParameters
.Builder()
.build();
consentInformation = UserMessagingPlatform.getConsentInformation(this);
consentInformation.requestConsentInfoUpdate(
this,
params,
(OnConsentInfoUpdateSuccessListener) () -> {
// TODO: Load and show the consent form.
},
(OnConsentInfoUpdateFailureListener) requestConsentError -> {
// Consent gathering failed.
Log.w(TAG, String.format("%s: %s",
requestConsentError.getErrorCode(),
requestConsentError.getMessage()));
});
}
}
Kotlin
package com.example.myapplication
import com.google.android.ump.ConsentInformation
import com.google.android.ump.ConsentInformation.OnConsentInfoUpdateFailureListener
import com.google.android.ump.ConsentInformation.OnConsentInfoUpdateSuccessListener
import com.google.android.ump.ConsentRequestParameters
import com.google.android.ump.UserMessagingPlatform
class MainActivity : AppCompatActivity() {
private lateinit var consentInformation: ConsentInformation
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
// Create a ConsentRequestParameters object.
val params = ConsentRequestParameters
.Builder()
.build()
consentInformation = UserMessagingPlatform.getConsentInformation(this)
consentInformation.requestConsentInfoUpdate(
this,
params,
ConsentInformation.OnConsentInfoUpdateSuccessListener {
// TODO: Load and show the consent form.
},
ConsentInformation.OnConsentInfoUpdateFailureListener {
requestConsentError ->
// Consent gathering failed.
Log.w(TAG, "${requestConsentError.errorCode}: ${requestConsentError.message}")
})
}
}
根据需要加载并显示用户意见征求表单
收到最新的用户意见征求状态后,请对ConsentForm
类调用loadAndShowConsentFormIfRequired()
以加载用户意见征求表单。如果需要征求用户意见,则 SDK 会加载一个表单,并立即 从提供的 activity中显示该表单。 callback
在表单关闭后 调用。如果不需要征得用户同意,系统会立即 callback
操作。
Java
public class MainActivity extends AppCompatActivity {
private ConsentInformation consentInformation;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
// Create a ConsentRequestParameters object.
ConsentRequestParameters params = new ConsentRequestParameters
.Builder()
.build();
consentInformation = UserMessagingPlatform.getConsentInformation(this);
consentInformation.requestConsentInfoUpdate(
this,
params,
(OnConsentInfoUpdateSuccessListener) () -> {
UserMessagingPlatform.loadAndShowConsentFormIfRequired(
this,
(OnConsentFormDismissedListener) loadAndShowError -> {
if (loadAndShowError != null) {
// Consent gathering failed.
Log.w(TAG, String.format("%s: %s",
loadAndShowError.getErrorCode(),
loadAndShowError.getMessage()));
}
// Consent has been gathered.
}
);
},
(OnConsentInfoUpdateFailureListener) requestConsentError -> {
// Consent gathering failed.
Log.w(TAG, String.format("%s: %s",
requestConsentError.getErrorCode(),
requestConsentError.getMessage()));
});
}
}
Kotlin
class MainActivity : AppCompatActivity() {
private lateinit var consentInformation: ConsentInformation
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
// Create a ConsentRequestParameters object.
val params = ConsentRequestParameters
.Builder()
.build()
consentInformation = UserMessagingPlatform.getConsentInformation(this)
consentInformation.requestConsentInfoUpdate(
this,
params,
ConsentInformation.OnConsentInfoUpdateSuccessListener {
UserMessagingPlatform.loadAndShowConsentFormIfRequired(
this@MainActivity,
ConsentForm.OnConsentFormDismissedListener {
loadAndShowError ->
if (loadAndShowError != null) {
// Consent gathering failed.
Log.w(TAG, "${loadAndShowError.errorCode}: ${loadAndShowError.message}")
}
// Consent has been gathered.
}
)
},
ConsentInformation.OnConsentInfoUpdateFailureListener {
requestConsentError ->
// Consent gathering failed.
Log.w(TAG, "${requestConsentError.errorCode}: ${requestConsentError.message}")
})
}
}
如果您需要在用户做出选择或关闭表单后执行操作,请将相应逻辑放入表单的 callback中。
提出广告请求
在应用中请求广告之前,请检查您是否已使用 canRequestAds()
征得用户的同意。征求用户意见时需要检查以下两个方面:
- 在当前会话中征求用户意见后。
- 调用
requestConsentInfoUpdate()
后立即执行。 可能已经在之前的会话中征得用户同意。作为延迟时间最佳做法,我们建议您不要等待回调完成,这样您就可以在应用启动后尽快开始加载广告。
如果在征求用户意见的过程中发生错误,您仍然应该尝试请求广告。UMP SDK 会使用上一个会话的用户意见征求状态。
Java
public class MainActivity extends AppCompatActivity {
private ConsentInformation consentInformation;
// Use an atomic boolean to initialize the Google Mobile Ads SDK and load ads once.
private final AtomicBoolean isMobileAdsInitializeCalled = new AtomicBoolean(false);
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
// Create a ConsentRequestParameters object.
ConsentRequestParameters params = new ConsentRequestParameters
.Builder()
.build();
consentInformation = UserMessagingPlatform.getConsentInformation(this);
consentInformation.requestConsentInfoUpdate(
this,
params,
(OnConsentInfoUpdateSuccessListener) () -> {
UserMessagingPlatform.loadAndShowConsentFormIfRequired(
this,
(OnConsentFormDismissedListener) loadAndShowError -> {
if (loadAndShowError != null) {
// Consent gathering failed.
Log.w(TAG, String.format("%s: %s",
loadAndShowError.getErrorCode(),
loadAndShowError.getMessage()));
}
// Consent has been gathered.
if (consentInformation.canRequestAds()) {
initializeMobileAdsSdk();
}
}
);
},
(OnConsentInfoUpdateFailureListener) requestConsentError -> {
// Consent gathering failed.
Log.w(TAG, String.format("%s: %s",
requestConsentError.getErrorCode(),
requestConsentError.getMessage()));
});
// Check if you can initialize the Google Mobile Ads SDK in parallel
// while checking for new consent information. Consent obtained in
// the previous session can be used to request ads.
if (consentInformation.canRequestAds()) {
initializeMobileAdsSdk();
}
}
private void initializeMobileAdsSdk() {
if (isMobileAdsInitializeCalled.getAndSet(true)) {
return;
}
new Thread(
() -> {
// Initialize the Google Mobile Ads SDK on a background thread.
MobileAds.initialize(this, initializationStatus -> {});
runOnUiThread(
() -> {
// TODO: Request an ad.
// InterstitialAd.load(...);
});
})
.start();
}
}
Kotlin
class MainActivity : AppCompatActivity() {
private lateinit var consentInformation: ConsentInformation
// Use an atomic boolean to initialize the Google Mobile Ads SDK and load ads once.
private var isMobileAdsInitializeCalled = AtomicBoolean(false)
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
// Create a ConsentRequestParameters object.
val params = ConsentRequestParameters
.Builder()
.build()
consentInformation = UserMessagingPlatform.getConsentInformation(this)
consentInformation.requestConsentInfoUpdate(
this,
params,
ConsentInformation.OnConsentInfoUpdateSuccessListener {
UserMessagingPlatform.loadAndShowConsentFormIfRequired(
this@MainActivity,
ConsentForm.OnConsentFormDismissedListener {
loadAndShowError ->
if (loadAndShowError != null) {
// Consent gathering failed.
Log.w(TAG, "${loadAndShowError.errorCode}: ${loadAndShowError.message}")
}
// Consent has been gathered.
if (consentInformation.canRequestAds()) {
initializeMobileAdsSdk()
}
}
)
},
ConsentInformation.OnConsentInfoUpdateFailureListener {
requestConsentError ->
// Consent gathering failed.
Log.w(TAG, "${requestConsentError.errorCode}: ${requestConsentError.message}")
})
// Check if you can initialize the Google Mobile Ads SDK in parallel
// while checking for new consent information. Consent obtained in
// the previous session can be used to request ads.
if (consentInformation.canRequestAds()) {
initializeMobileAdsSdk()
}
}
private fun initializeMobileAdsSdk() {
if (isMobileAdsInitializeCalled.getAndSet(true)) {
return
}
val backgroundScope = CoroutineScope(Dispatchers.IO)
backgroundScope.launch {
// Initialize the Google Mobile Ads SDK on a background thread.
MobileAds.initialize(this@MainActivity) {}
// TODO: Request an ad.
// InterstitialAd.load(...)
}
}
}
隐私设置选项
一些用户意见征求表单要求用户随时修改同意声明。如需实现隐私权选项按钮(如果需要),请按照以下步骤操作。
要实现这一目标,需要完成以下步骤:
- 实现可以触发隐私权选项表单的界面元素,例如应用设置页面中的按钮。
-
loadAndShowConsentFormIfRequired()
完成后,请检查privacyOptionsRequirementStatus()
,以确定是否显示可以呈现隐私选项表单的界面元素。 - 当用户与您的界面元素互动时,调用
showPrivacyOptionsForm()
以显示该表单,以便用户随时更新其隐私选项。
以下示例展示了如何从 MenuItem
显示隐私权选项表单。
Java
private final ConsentInformation consentInformation;
// Show a privacy options button if required.
public boolean isPrivacyOptionsRequired() {
return consentInformation.getPrivacyOptionsRequirementStatus()
== PrivacyOptionsRequirementStatus.REQUIRED;
}
@Override
protected void onCreate(Bundle savedInstanceState) {
// ...
consentInformation = UserMessagingPlatform.getConsentInformation(this);
consentInformation.requestConsentInfoUpdate(
this,
params,
(OnConsentInfoUpdateSuccessListener) () -> {
UserMessagingPlatform.loadAndShowConsentFormIfRequired(
this,
(OnConsentFormDismissedListener) loadAndShowError -> {
// ...
// Consent has been gathered.
if (isPrivacyOptionsRequired()) {
// Regenerate the options menu to include a privacy setting.
invalidateOptionsMenu();
}
}
)
}
// ...
}
@Override
public boolean onCreateOptionsMenu(Menu menu) {
getMenuInflater().inflate(R.menu.action_menu, menu);
MenuItem moreMenu = menu.findItem(R.id.action_more);
moreMenu.setVisible(isPrivacyOptionsRequired());
return true;
}
@Override
public boolean onOptionsItemSelected(MenuItem item) {
// ...
popup.setOnMenuItemClickListener(
popupMenuItem -> {
if (popupMenuItem.getItemId() == R.id.privacy_settings) {
// Present the privacy options form when a user interacts with
// the privacy settings button.
UserMessagingPlatform.showPrivacyOptionsForm(
this,
formError -> {
if (formError != null) {
// Handle the error.
}
}
);
return true;
}
return false;
});
return super.onOptionsItemSelected(item);
}
Kotlin
private val consentInformation: ConsentInformation =
UserMessagingPlatform.getConsentInformation(context)
// Show a privacy options button if required.
val isPrivacyOptionsRequired: Boolean
get() =
consentInformation.privacyOptionsRequirementStatus ==
ConsentInformation.PrivacyOptionsRequirementStatus.REQUIRED
override fun onCreate(savedInstanceState: Bundle?) {
...
consentInformation = UserMessagingPlatform.getConsentInformation(this)
consentInformation.requestConsentInfoUpdate(
this,
params,
ConsentInformation.OnConsentInfoUpdateSuccessListener {
UserMessagingPlatform.loadAndShowConsentFormIfRequired(
this@MainActivity,
ConsentForm.OnConsentFormDismissedListener {
// ...
// Consent has been gathered.
if (isPrivacyOptionsRequired) {
// Regenerate the options menu to include a privacy setting.
invalidateOptionsMenu();
}
}
)
}
// ...
}
override fun onCreateOptionsMenu(menu: Menu?): Boolean {
menuInflater.inflate(R.menu.action_menu, menu)
menu?.findItem(R.id.action_more)?.apply {
isVisible = isPrivacyOptionsRequired
}
return super.onCreateOptionsMenu(menu)
}
override fun onOptionsItemSelected(item: MenuItem): Boolean {
// ...
popup.setOnMenuItemClickListener { popupMenuItem ->
when (popupMenuItem.itemId) {
R.id.privacy_settings -> {
// Present the privacy options form when a user interacts with
// the privacy settings button.
UserMessagingPlatform.showPrivacyOptionsForm(this) { formError ->
formError?.let {
// Handle the error.
}
}
true
}
else -> false
}
}
return super.onOptionsItemSelected(item)
}
测试
如果您希望在开发过程中测试应用中的集成,请按照以下步骤以编程方式注册测试设备。在发布应用之前,请务必移除用于设置这些测试设备 ID 的代码。
- 调用
requestConsentInfoUpdate()
。 检查日志输出是否存在类似于以下示例的消息,该示例显示了您的设备 ID 以及如何将其添加为测试设备:
Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("33BE2250B43518CCDA7DE426D04EE231") to set this as a debug device.
将测试设备 ID 复制到剪贴板。
修改代码, 调用
ConsentDebugSettings.Builder().addTestDeviceHashedId()
,并传入 测试设备 ID 列表。
强制设置地理位置
UMP SDK 可让您使用 the setDebugGeography()
method which takes a DebugGeography
on ConsentDebugSettings.Builder
来测试应用的行为,就像设备位于欧洲经济区 (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 | Kotlin