根据 Google 欧盟地区用户意见征求政策,您必须向位于欧洲经济区 (EEA) 以及英国境内的用户披露相关信息,在法律有相应要求的情况下,必须征得他们的同意才能使用 Cookie 或其他本地存储方式,以及使用个人数据(例如 AdID)来投放广告。此政策反映了欧盟《电子隐私指令》和《一般数据保护条例》(GDPR) 的要求。
为了帮助发布商履行此政策规定的职责,Google 提供了 User Messaging Platform (UMP) SDK。UMP SDK 已更新,可支持最新的 IAB 标准。现在,所有这些配置都可以在 AdMob 隐私权和消息中方便地处理。
前提条件
- 完成入门指南
- Android API 级别 21 或更高级别(适用于 Android)
- 如果您正在处理与 GDPR 相关的要求,请参阅IAB 要求对欧盟地区用户意见征求消息的影响
创建消息类型
在您的 AdMob 账号的隐私权和消息标签页下,使用 可用的用户消息类型 创建用户消息。UMP SDK 会尝试显示通过您项目中设置的 AdMob 应用 ID 创建的用户消息。如果没有为您的应用配置消息,SDK 将返回错误。
如需了解详情,请参阅 隐私权和消息简介。
安装 SDK
按照相应步骤安装 Google 移动广告 (GMA) C++ SDK。UMP C++ SDK 包含在 GMA C++ SDK 中。
请务必先在项目中配置应用的 AdMob 应用 ID,然后再继续操作。
在代码中,通过调用
ConsentInfo::GetInstance()
初始化 UMP SDK。- 在 Android 上,您需要传入 NDK 提供的
JNIEnv
和Activity
。您只需在首次调用GetInstance()
时执行此操作。 - 或者,如果您已在应用中使用 Firebase C++ SDK,则可以在首次调用
GetInstance()
时传入firebase::App
。
#include "firebase/gma/ump.h" namespace ump = ::firebase::gma::ump; // Initialize using a firebase::App void InitializeUserMessagingPlatform(const firebase::App& app) { ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance(app); } // Initialize without a firebase::App #ifdef ANDROID void InitializeUserMessagingPlatform(JNIEnv* jni_env, jobject activity) { ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance(jni_env, activity); } #else // non-Android void InitializeUserMessagingPlatform() { ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance(); } #endif
- 在 Android 上,您需要传入 NDK 提供的
对 ConsentInfo::GetInstance()
的后续调用均返回相同的实例。
用完 UMP SDK 后,您可以通过删除 ConsentInfo
实例来关停 SDK:
void ShutdownUserMessagingPlatform() {
ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();
delete consent_info;
}
使用 Future
监控异步操作
firebase::Future
提供了一种方法来确定异步方法调用的完成状态。
异步运行的所有 UMP C++ 函数和方法调用都会返回 Future
,还会提供“最后的结果”函数,以从最近的操作中检索 Future
。
您可以通过以下两种方式从 Future
获取结果:
- 调用
OnCompletion()
,并传入您自己的回调函数,该函数在操作完成时调用。 - 定期检查
Future
的status()
。当状态从kFutureStatusPending
变为kFutureStatusCompleted
时,表示操作已完成。
异步操作完成后,您应检查 Future
的 error()
以获取操作的错误代码。如果错误代码为 0
(kConsentRequestSuccess
或 kConsentFormSuccess
),则表示操作已成功完成;否则,请检查错误代码和 error_message()
以确定问题所在。
完成回调
以下示例展示了如何使用 OnCompletion
设置完成回调函数,该回调函数在异步操作完成时被调用。
void MyApplicationStart() {
// [... other app initialization code ...]
ump::ConsentInfo *consent_info = ump::ConsentInfo::GetInstance();
// See the section below for more information about RequestConsentInfoUpdate.
firebase::Future<void> result = consent_info->RequestConsentInfoUpdate(...);
result.OnCompletion([](const firebase::Future<void>& req_result) {
if (req_result.error() == ump::kConsentRequestSuccess) {
// Operation succeeded. You can now call LoadAndShowConsentFormIfRequired().
} else {
// Operation failed. Check req_result.error_message() for more information.
}
});
}
更新循环轮询
在此示例中,在应用启动时启动异步操作后,系统会在游戏的更新循环函数(每帧运行一次)中的其他位置检查结果。
ump::ConsentInfo *g_consent_info = nullptr;
bool g_waiting_for_request = false;
void MyApplicationStart() {
// [... other app initialization code ...]
g_consent_info = ump::ConsentInfo::GetInstance();
// See the section below for more information about RequestConsentInfoUpdate.
g_consent_info->RequestConsentInfoUpdate(...);
g_waiting_for_request = true;
}
// Elsewhere, in the game's update loop, which runs once per frame:
void MyGameUpdateLoop() {
// [... other game logic here ...]
if (g_waiting_for_request) {
// Check whether RequestConsentInfoUpdate() has finished.
// Calling "LastResult" returns the Future for the most recent operation.
firebase::Future<void> result =
g_consent_info->RequestConsentInfoUpdateLastResult();
if (result.status() == firebase::kFutureStatusComplete) {
g_waiting_for_request = false;
if (result.error() == ump::kConsentRequestSuccess) {
// Operation succeeded. You can call LoadAndShowConsentFormIfRequired().
} else {
// Operation failed. Check result.error_message() for more information.
}
}
}
}
如需详细了解 firebase::Future
,请参阅 Firebase C++ SDK 文档和 GMA C++ SDK 文档。
征求用户同意
您应在每次启动应用时使用 RequestConsentInfoUpdate()
请求更新用户的用户意见征求信息。这决定了您的用户是否需要提供同意声明(如果尚未提供)或同意情况已过期。
#include "firebase/gma/ump.h"
namespace ump = ::firebase::gma::ump;
void MyApplicationStart() {
ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();
// Create a ConsentRequestParameters struct.
ump::ConsentRequestParameters params;
// Set tag for under age of consent. False means users are NOT under age
// of consent.
params.tag_for_under_age_of_consent = false;
consent_info->RequestConsentInfoUpdate(params).OnCompletion(
[](const Future<void>& result) {
if (result.error() != ump::kConsentRequestSuccess) {
LogMessage("Error requesting consent update: %s", result.error_message());
} else {
// Consent status is now available.
}
});
}
如需查看使用更新循环轮询(而不是完成回调)检查完成情况的示例,请参阅上文。
根据需要加载并显示用户意见征求表单
收到最新的同意情况后,请对ConsentInfo
类调用LoadAndShowConsentFormIfRequired()
以加载用户意见征求表单。如果需要用户意见状态,SDK 会加载一个表单,并 通过提供的 FormParent
立即显示该表单。在用户关闭表单后,系统会调用 Future
已完成 。如果不需要征得用户同意,系统会立即 Future
完成 。
void MyApplicationStart(ump::FormParent parent) {
ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();
// Create a ConsentRequestParameters struct..
ump::ConsentRequestParameters params;
// Set tag for under age of consent. False means users are NOT under age of consent.
params.tag_for_under_age_of_consent = false;
consent_info->RequestConsentInfoUpdate(params).OnCompletion(
[*](const Future<void>& req_result) {
if (req_result.error() != ump::kConsentRequestSuccess) {
// req_result.error() is a kConsentRequestError enum.
LogMessage("Error requesting consent update: %s", req_result.error_message());
} else {
consent_info->LoadAndShowConsentFormIfRequired(parent).OnCompletion(
[*](const Future<void>& form_result) {
if (form_result.error() != ump::kConsentFormSuccess) {
// form_result.error() is a kConsentFormError enum.
LogMessage("Error showing consent form: %s", form_result.error_message());
} else {
// Either the form was shown and completed by the user, or consent was not required.
}
});
}
});
}
如果您需要在用户做出选择或关闭表单后执行任何操作,请将相应逻辑放在处理 LoadAndShowConsentFormIfRequired()
返回的 Future
的代码中。
提出广告请求
在您的应用中请求广告之前,请检查您是否已使用 ConsentInfo::GetInstance()‑>CanRequestAds()
征得用户同意。在征求用户意见时,有两个位置可供检查:
- 在当前会话中收集用户意见后。
- 调用
RequestConsentInfoUpdate()
后。可能已在上一次会话中征得用户同意。为缩短延迟时间,我们建议不要等待回调完成,以便在应用启动后尽快开始加载广告。
如果在征求用户意见的过程中出现错误,您仍应尝试请求广告。UMP SDK 会使用上一会话中的用户同意情况。
以下完整示例使用了更新循环轮询,但您也可以使用 OnCompletion
回调来监控异步操作。请以更适合您的代码结构的技术为准。
#include "firebase/future.h"
#include "firebase/gma/gma.h"
#include "firebase/gma/ump.h"
namespace gma = ::firebase::gma;
namespace ump = ::firebase::gma::ump;
using firebase::Future;
ump::ConsentInfo* g_consent_info = nullptr;
// State variable for tracking the UMP consent flow.
enum { kStart, kRequest, kLoadAndShow, kInitGma, kFinished, kErrorState } g_state = kStart;
bool g_ads_allowed = false;
void MyApplicationStart() {
g_consent_info = ump::ConsentInfo::GetInstance(...);
// Create a ConsentRequestParameters struct..
ump::ConsentRequestParameters params;
// Set tag for under age of consent. False means users are NOT under age of consent.
params.tag_for_under_age_of_consent = false;
g_consent_info->RequestConsentInfoUpdate(params);
// CanRequestAds() can return a cached value from a previous run immediately.
g_ads_allowed = g_consent_info->CanRequestAds();
g_state = kRequest;
}
// This function runs once per frame.
void MyGameUpdateLoop() {
// [... other game logic here ...]
if (g_state == kRequest) {
Future<void> req_result = g_consent_info->RequestConsentInfoUpdateLastResult();
if (req_result.status() == firebase::kFutureStatusComplete) {
g_ads_allowed = g_consent_info->CanRequestAds();
if (req_result.error() == ump::kConsentRequestSuccess) {
// You must provide the FormParent (Android Activity or iOS UIViewController).
ump::FormParent parent = GetMyFormParent();
g_consent_info->LoadAndShowConsentFormIfRequired(parent);
g_state = kLoadAndShow;
} else {
LogMessage("Error requesting consent status: %s", req_result.error_message());
g_state = kErrorState;
}
}
}
if (g_state == kLoadAndShow) {
Future<void> form_result = g_consent_info->LoadAndShowConsentFormIfRequiredLastResult();
if (form_result.status() == firebase::kFutureStatusComplete) {
g_ads_allowed = g_consent_info->CanRequestAds();
if (form_result.error() == ump::kConsentRequestSuccess) {
if (g_ads_allowed) {
// Initialize GMA. This is another asynchronous operation.
firebase::gma::Initialize();
g_state = kInitGma;
} else {
g_state = kFinished;
}
// Optional: shut down the UMP SDK to save memory.
delete g_consent_info;
g_consent_info = nullptr;
} else {
LogMessage("Error displaying consent form: %s", form_result.error_message());
g_state = kErrorState;
}
}
}
if (g_state == kInitGma && g_ads_allowed) {
Future<gma::AdapterInitializationStatus> gma_future = gma::InitializeLastResult();
if (gma_future.status() == firebase::kFutureStatusComplete) {
if (gma_future.error() == gma::kAdErrorCodeNone) {
g_state = kFinished;
// TODO: Request an ad.
} else {
LogMessage("Error initializing GMA: %s", gma_future.error_message());
g_state = kErrorState;
}
}
}
}
隐私设置选项
有些用户意见征求表单会要求用户随时修改同意情况。请根据需要按照以下步骤实现隐私权选项按钮。
要实现这一目标,需要完成以下步骤:
- 实现可触发隐私权选项表单的界面元素,例如应用的设置页面中的按钮。
-
LoadAndShowConsentFormIfRequired()
完成后,请检查getPrivacyOptionsRequirementStatus()
以确定是否显示可呈现隐私权选项表单的界面元素。 - 当用户与您的界面元素交互时,调用
showPrivacyOptionsForm()
以显示该表单,以便用户能够随时更新其隐私选项。
测试
如果您希望在开发过程中测试应用中的集成,请按照以下步骤以编程方式注册测试设备。在发布应用之前,请务必移除设置这些测试设备 ID 的代码。
- 致电
RequestConsentInfoUpdate()
。 检查日志输出中是否有类似于以下示例的消息,该消息显示了您的设备 ID 以及如何将其添加为测试设备:
Android
Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("33BE2250B43518CCDA7DE426D04EE231") to set this as a debug device.
iOS
<UMP SDK>To enable debug mode for this device, set: UMPDebugSettings.testDeviceIdentifiers = @[2077ef9a63d2b398840261c8221a0c9b]
将测试设备 ID 复制到剪贴板。
修改代码,将 设置为
ConsentRequestParameters.debug_settings.debug_device_ids
您的测试设备 ID 列表。void MyApplicationStart() { ump::ConsentInfo consent_info = ump::ConsentInfo::GetInstance(...); ump::ConsentRequestParameters params; params.tag_for_under_age_of_consent = false; params.debug_settings.debug_device_ids = {"TEST-DEVICE-HASHED-ID"}; consent_info->RequestConsentInfoUpdate(params); }
强制指定地理位置
UMP SDK 提供了一种方法,可让您使用 ConsentRequestParameters.debug_settings.debug_geography
测试应用的行为,就如同设备位于欧洲经济区 (EEA) 或英国一样。请注意,调试设置仅适用于测试设备。
void MyApplicationStart() {
ump::ConsentInfo consent_info = ump::ConsentInfo::GetInstance(...);
ump::ConsentRequestParameters params;
params.tag_for_under_age_of_consent = false;
params.debug_settings.debug_device_ids = {"TEST-DEVICE-HASHED-ID"};
// Geography appears as EEA for debug devices.
params.debug_settings.debug_geography = ump::kConsentDebugGeographyEEA
consent_info->RequestConsentInfoUpdate(params);
}
重置同意情况
使用 UMP SDK 测试应用时,您可能会发现重置 SDK 的状态很有用,这样您就可以模拟用户的首次安装体验。为此,SDK 提供了 Reset()
方法。
ConsentInfo::GetInstance()->Reset();