Google User Messaging Platform (UMP) SDK 是一項隱私權與訊息工具，可協助您管理隱私權選項。詳情請參閱「關於隱私權與訊息」。
必要條件
- Android API 級別 21 以上版本 (適用於 Android)
建立訊息類型
在 AdMob 帳戶的「隱私權與訊息」分頁中，使用「可用的使用者訊息類型」建立使用者訊息。UMP SDK 會嘗試顯示使用專案中設定的 AdMob 應用程式 ID 建立的隱私權訊息。
詳情請參閱「關於隱私權和訊息」。
安裝 SDK
按照步驟安裝 Firebase C++ SDK。UMP C++ SDK 隨附於 Firebase C++ SDK。
請務必先在專案中設定應用程式的 AdMob 應用程式 ID，再繼續操作。
在程式碼中呼叫
ConsentInfo::GetInstance()，初始化 UMP SDK。- 在 Android 上，您需要傳入 NDK 提供的
JNIEnv和Activity。您只需要在第一次呼叫GetInstance()時執行這項操作。 - 或者，如果您已在應用程式中使用 Firebase C++ SDK，可以在第一次呼叫
GetInstance()時傳遞firebase::App。
#include "firebase/ump/ump.h" namespace ump = ::firebase::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 監控非同步作業
A 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/ump/ump.h" namespace ump = ::firebase::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()); } // Consent information is successfully updated. }); } 載入並顯示隱私權訊息表單
收到最新的同意聲明狀態後，請呼叫 LoadAndShowConsentFormIfRequired()，載入收集使用者同意聲明所需的表單。載入後，表單會立即顯示。
#include "firebase/ump/ump.h" namespace ump = ::firebase::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() 檢查是否已取得使用者同意聲明：
收集同意聲明時，請檢查下列位置是否可以要求廣告：
- 在目前工作階段中，UMP SDK 收集同意聲明後。
- 呼叫
RequestConsentInfoUpdate()後立即執行。UMP SDK 可能已在上一個應用程式工作階段取得同意聲明。
如果在收集同意聲明的過程中發生錯誤，請檢查是否可以請求廣告。UMP SDK 會使用上一個應用程式工作階段的同意聲明狀態。
下列完整範例使用更新迴圈輪詢，但您也可以使用 OnCompletion 回呼監控非同步作業。請使用較適合程式碼結構的技術。
#include "firebase/future.h" #include "firebase/gma/gma.h" #include "firebase/ump/ump.h" namespace gma = ::firebase::gma; namespace ump = ::firebase::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();