开始使用

Google User Messaging Platform (UMP) SDK 是一款隐私权和消息工具，可帮助您管理隐私选项。如需了解详情，请参阅“隐私权和消息”页面简介。

前提条件

• Android API 级别 21 或更高级别（适用于 Android）

创建消息类型

在 AdMob 账号的隐私权和消息标签页下，使用其中一种可用的用户消息类型创建用户消息。UMP SDK 会尝试显示根据您在项目中设置的 AdMob 应用 ID 创建的隐私权消息。

如需了解详情，请参阅隐私权和消息简介。

安装 SDK

1. 按照相应步骤安装 Google 移动广告 (GMA) C++ SDK。GMA C++ SDK 中包含 UMP 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 移动广告 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>。

征求用户意见

如需征求用户同意，请完成以下步骤：

1. 请求获取最新的用户意见征求信息。
2. 根据需要加载并显示用户意见征求表单。

请求提供意见征求信息

每次启动应用时，您都应使用 RequestConsentInfoUpdate() 请求更新用户的意见征求信息。此请求会检查以下内容：

• 是否需要征得用户同意。例如，首次需要征得用户同意，或者之前的用户意见征求结果已过期。
• 是否必须提供隐私设置选项入口点。某些隐私权消息要求应用允许用户随时修改其隐私选项。

警告： 如果用户意见征求已过期，使用其他方式（例如应用中的缓存或之前保存的用户意见征求字符串）查看用户意见征求状态可能会导致 TCF 3.3 错误。

根据需要加载和显示隐私权消息表单

收到最新的意见征求状态后，调用 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.
          }
        });
      }
    });
}

请参阅上文，查看使用更新循环轮询（而非完成回调）检查是否已完成的示例。

注意： 根据平台，FormParent 要么是指向 Android Activity 的 JNI jobject 引用，要么是指向 iOS UIViewController 的指针，并转换为 FormParent 类型。

如果您需要在用户做出选择或关闭表单后执行操作，请将相应逻辑放入处理 LoadAndShowConsentFormIfRequired() 返回的 Future 的代码中。

隐私选项

某些隐私权消息表单会通过发布商呈现的隐私权选项入口点显示，以便用户随时管理其隐私权选项。如需详细了解您的用户会在隐私权选项入口点看到哪条消息，请参阅可用的用户消息类型。

提出广告请求

在应用中请求展示广告之前，请检查您是否已使用 ConsentInfo::GetInstance()‑> CanRequestAds() 征得用户同意。在征求用户意见时，您可以检查以下两个位置：

• 在当前会话中征得用户同意后。
• 在调用 RequestConsentInfoUpdate() 后立即调用。系统可能已在上一会话中征得用户同意。延迟时间最佳实践：我们建议您不要等待回调完成，以便在应用启动后尽快开始加载广告。

注意： 在您调用 RequestConsentInfoUpdate() 之前， ConsentInfo::GetInstance()‑> CanRequestAds() 始终会返回 false

如果在征求用户同意的过程中发生错误，您仍应检查自己是否可以请求展示广告。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 的代码。

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 提供了一种方法：使用 debug_settings.debug_geography 测试您的应用行为，就像设备位于欧洲经济区 (EEA) 或英国境内一样。请注意，调试设置仅适用于测试设备。

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()。