Google User Messaging Platform (UMP) SDK 是隱私權和訊息工具,可協助您管理隱私權選項。詳情請參閱「關於隱私權與訊息」一文。
必要條件
- Android API 級別 21 以上 (適用於 Android)
建立訊息類型
在 AdMob 帳戶的「隱私權與訊息」分頁中,使用任一可用的使用者訊息類型建立使用者訊息。UMP SDK 會嘗試顯示根據專案中設定的 AdMob 應用程式 ID 建立的隱私權訊息。
詳情請參閱「關於隱私權和訊息」。
安裝 SDK
按照步驟安裝 Google Mobile Ads (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()
要求更新使用者的同意聲明資訊。這項要求會檢查下列項目:
- 是否需要取得同意聲明。例如,首次使用時需要取得同意聲明,或是先前的同意聲明已過期。
- 是否需要隱私權選項進入點。部分隱私權訊息要求應用程式允許使用者隨時修改隱私權選項。
載入並顯示隱私權訊息表單 (如有需要)
收到最新的同意聲明狀態後,請呼叫
LoadAndShowConsentFormIfRequired()
來載入收集使用者同意聲明所需的任何表單。表單載入後會立即顯示。
以下程式碼示範如何要求使用者的最新同意聲明資訊。如有需要,程式碼會載入並顯示隱私權訊息表單:
#include "firebase/gma/ump.h"
namespace ump = ::firebase::gma::ump;
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 privacy message 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 privacy message 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;
}
}
}
}
測試
如要在開發過程中測試應用程式的整合作業,請按照下列步驟,以程式輔助方式註冊測試裝置。發布應用程式之前,請務必移除用來設定這些測試裝置 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 可讓您使用 debug_settings.debug_geography
,測試應用程式行為,就像裝置位於不同區域 (例如歐洲經濟區或英國) 一樣。請注意,偵錯設定只適用於測試裝置。
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();