本頁面由 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()，在每次啟動應用程式時要求更新使用者的同意聲明資訊。這項要求會檢查以下項目：

是否需要取得同意聲明。例如，首次使用時需要取得同意聲明，或是先前的同意聲明已過期。
是否需要隱私權選項進入點。部分隱私權訊息要求應用程式允許使用者隨時修改隱私權選項。

#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());
      }
      // Consent information is successfully updated.
    });
}

載入並顯示隱私權訊息表單

收到最新的同意聲明狀態後，請呼叫 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() 檢查您是否已取得使用者的同意聲明：

如要瞭解您是否可以在收集同意聲明時要求顯示廣告，請查看下列位置：

UMP SDK 在目前的工作階段中收集同意聲明後。
呼叫 RequestConsentInfoUpdate() 後立即執行。UMP SDK 可能在先前的應用程式工作階段中取得同意聲明。

如果在同意聲明收集程序中發生錯誤，請檢查是否可以要求廣告。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();