Google User Messaging Platform (UMP) SDK 是一項隱私權與訊息工具, 協助您管理隱私權選擇若需更多資訊,請參閲 關於隱私權與訊息。
必要條件
- Android API 級別 21 以上 (Android 專用)
建立訊息類型
使用以下其中一則文字建立使用者訊息: 可用的使用者訊息類型 中,隱私權與訊息分頁 AdMob 。 讓他們使用服務帳戶UMP SDK 會嘗試顯示 從應用程式 ID AdMob 建立的隱私權訊息 您在專案中設定的內容
詳情請參閱 關於隱私權與訊息。
安裝 SDK
請按照下列步驟安裝 Google 行動廣告 (GMA) C++ SDK。UMP C++ GMA C++ SDK 已納入 SDK。
請務必設定應用程式的 AdMob 應用程式 專案中的 ID 才能繼續。
在程式碼中,呼叫
ConsentInfo::GetInstance()
。- 在 Android 上,您需要傳入
JNIEnv
和Activity
NDK只有在首次呼叫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 上,您需要傳入
後續呼叫 ConsentInfo::GetInstance()
時,所有呼叫都會傳回同一個例項。
已使用 UMP SDK 後,只要刪除
ConsentInfo
執行個體:
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 說明文件
新增應用程式 ID
您可以在「 AdMob UI: 將身分證件新增至 替換為下列程式碼片段:
要求同意聲明資訊
在每個應用程式中,應要求使用者更新同意聲明資訊
使用 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.
}
});
}
請參閱上述範例,瞭解如何使用 update 迴圈輪詢,而非完成回呼。
視需要載入並顯示隱私權訊息表單
收到最新的同意聲明狀態後,請致電
LoadAndShowConsentFormIfRequired()
即可載入任何必要的表單,
收集使用者同意聲明表單載入後會立即顯示。
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.
}
});
}
});
}
您需要在使用者做出選擇或關閉廣告後執行任何動作
表單,請將該邏輯放入處理 Future
的程式碼中
由 LoadAndShowConsentFormIfRequired()
傳回。
隱私權選項
部分隱私權訊息表單是由發布商顯示的隱私權提供 選項進入點,讓使用者隨時管理自己的隱私權選項。 如要進一步瞭解使用者會看到哪些訊息,請透過隱私權選項 進入點,請參閱 可用的使用者訊息類型:
如要實作隱私權選項進入點,請完成下列步驟:
- 請檢查
getPrivacyOptionsRequirementStatus()
。 - 如果隱私權選項進入點 您必須在應用程式中加入可見且可互動的 UI 元素。
- 使用以下程式碼觸發隱私權選項表單:
showPrivacyOptionsForm()
。
以下程式碼範例會示範這些步驟:
請求廣告
在應用程式中請求廣告前,請確認您已取得同意聲明
透過 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 可讓您測試應用程式行為,就像測試裝置
地址在歐洲經濟區或英國境內,並使用 ConsentRequestParameters.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();