開始使用

根據 Google《歐盟地區使用者同意授權政策》規定，您必須向歐洲經濟區 (EEA) 和英國境內的使用者揭露特定資訊，且必須依法取得使用者同意，才能使用 Cookie 或其他本機儲存空間，以及使用個人資料 (例如廣告 ID) 放送廣告。本政策是配合《歐盟地區電子通訊隱私指令》和《一般資料保護規則》(GDPR) 而製定。

為了協助發布商根據這項政策履行自身職責，Google 提供了 User Messaging Platform (UMP) SDK。UMP SDK 已更新，現已支援最新的 IAB 標準。這些設定現在全都可在隱私權與訊息中 AdMob 輕鬆處理。

先備知識

• 完整閱讀入門指南

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

• 如果您正在處理 GDPR 相關規定，請參閱IAB 規定對歐盟地區同意授權訊息的影響

建立訊息類型

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

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

安裝 SDK

1. 按照步驟安裝 Google Mobile Ads (GMA) C++ SDK。UMP C++ SDK 包含在 GMA C++ SDK 中，

2. 請先在專案中設定應用程式的 AdMob 應用程式 ID，再繼續操作。

3. 在程式碼中，呼叫 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() 時，所有呼叫都會傳回同一個例項。

注意： GetInstance() 方法有選用的 firebase::InitResult 輸出參數，可在 SDK 成功初始化時傳回 firebase::kInitResultSuccess；如果應用程式缺少任何必要依附元件，則會傳回 firebase::kInitResultFailedMissingDependency。如果發生這個錯誤，請確認您已按照平台適用的所有安裝步驟操作。

如果您已經完成了 UMP SDK 的使用程序，可以刪除 ConsentInfo 執行個體來關閉 SDK：

void ShutdownUserMessagingPlatform() {
  ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();
  delete consent_info;
}

注意： 您不需要先初始化 Google Mobile Ads C++ SDK，就能初始化 User Messaging Platform SDK。

使用 Future 監控非同步作業

firebase::Future 可讓您判斷非同步方法呼叫的完成狀態。

所有以非同步方式運作的 UMP C++ 函式和方法呼叫都會傳回 Future，並提供「最後一個結果」函式，以便從最近的作業中擷取 Future。

有兩種方法可以從 Future 取得結果：

1. 呼叫 OnCompletion()，並傳入您自己的回呼函式，系統會在作業完成時呼叫這個函式。
2. 定期檢查 Future 的 status()。當狀態從 kFutureStatusPending 變更為 kFutureStatusCompleted 時，即代表作業已完成。

非同步作業完成後，請檢查 Future 的 error() 來取得作業的錯誤代碼。如果錯誤代碼為 0 (kConsentRequestSuccess 或 kConsentFormSuccess)，表示作業已成功完成；否則，請查看錯誤代碼和 error_message()，找出發生錯誤的原因。

注意： RequestConsentInfoUpdate() 傳回的錯誤代碼使用列舉 ConsentRequestError；所有其他作業都使用 ConsentFormError。

完成回呼

以下範例說明如何使用 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 說明文件。

注意： 在 UMP C++ SDK 中，所有非同步作業都會傳回 firebase::Future<void>。

要求同意聲明資訊

您應在每次應用程式啟動時，使用 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.
      }
    });
}

如需使用更新迴圈輪詢 (而非完成回呼) 檢查完成的範例，請參閱上述範例。

警告： 如果同意聲明失效，使用其他方式檢查同意聲明狀態 (例如應用程式快取或先前儲存的同意聲明字串)，可能會導致資訊公開和同意聲明架構 3.3 錯誤。

視需要載入並顯示同意聲明表單

收到最新的同意聲明狀態後，請對ConsentInfo 類別呼叫LoadAndShowConsentFormIfRequired() 以載入同意聲明表單。如果需要同意聲明狀態，SDK 會載入表單，並立即透過 提供的 FormParent顯示表單。關閉表單後，系統會 Future 完成 。如果不需要徵求同意，系統會立即 Future 完成 。

注意： 視平台而定， FormParent 可以是 Android Activity 的 JNI jobject 或指向 iOS UIViewController 的指標，可轉換為 FormParent 類型。

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 consent 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()取得使用者的同意聲明。收集同意聲明時，需要檢查兩個地方：

1. 從目前的工作階段中收集到同意聲明後，
2. 呼叫 RequestConsentInfoUpdate()後立即執行。您可能已在上一個工作階段取得同意聲明。建議您最好不要等待回呼完成，以便在應用程式啟動後盡快載入廣告。

注意： ConsentInfo::GetInstance()‑>CanRequestAds() 一律會傳回 false，直到您呼叫 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 consent 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;
      }
    }
  }
}

隱私權選項

部分同意聲明表單會要求使用者隨時修改同意聲明。如有需要，請按照下列步驟導入隱私權選項按鈕。

為了達到這個目的：

1. 實作可觸發隱私權選項表單的 UI 元素，例如應用程式設定頁面中的按鈕。
2. 完成 LoadAndShowConsentFormIfRequired() 完成後，請檢查getPrivacyOptionsRequirementStatus() 判斷是否要顯示能顯示隱私權選項表單的 UI 元素。
3. 當使用者與您的 UI 元素互動時，請呼叫showPrivacyOptionsForm() 來顯示表單，方便使用者隨時更新隱私權選項。

測試

如要在開發過程中測試應用程式的整合作業，請按照下列步驟，以程式輔助方式註冊測試裝置。發布應用程式之前，請務必移除用來設定這些測試裝置 ID 的程式碼。

1. 呼叫 RequestConsentInfoUpdate()。

2. 查看記錄輸出中是否有類似以下範例的訊息，這些訊息顯示您的裝置 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]
   

3. 將測試裝置 ID 複製到剪貼簿。

4. 修改程式碼以 設定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();

注意： 這個方法僅供測試。不應在正式版程式碼中呼叫 Reset() 。