本頁面由 Cloud Translation API 翻譯而成。

瞭解詳情

Google User Messaging Platform (UMP) SDK 是一項隱私權與訊息傳遞工具，可協助您管理隱私權選擇。詳情請參閱「關於隱私權與訊息」一文。

必要條件

Android API 級別 21 以上版本 (適用於 Android)

建立訊息類型

請在 AdMob 帳戶的「隱私權與訊息」分頁中，使用其中一種可用的使用者訊息類型建立使用者訊息。UMP SDK 會嘗試顯示根據專案中設定的 AdMob 應用程式 ID 建立的隱私權訊息。

詳情請參閱「關於隱私權和訊息」。

安裝 SDK

請按照這篇文章中的步驟安裝 Google Mobile Ads (GMA) C++ SDK。GMA C++ SDK 包含 UMP 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

後續對 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();