此页面由 Cloud Translation API 翻译。

开始使用

根据 Google 欧盟地区用户意见征求政策，您必须向位于欧洲经济区 (EEA) 以及英国境内的用户披露相关信息，在法律有相应要求的情况下，必须征得他们的同意才能使用 Cookie 或其他本地存储方式，以及使用个人数据（例如 AdID）来投放广告。此政策反映了欧盟《电子隐私指令》和《一般数据保护条例》(GDPR) 的要求。

为了帮助发布商履行此政策规定的职责，Google 提供了 User Messaging Platform (UMP) SDK。UMP SDK 已更新，可支持最新的 IAB 标准。现在，所有这些配置都可以在 AdMob 隐私权和消息中方便地处理。

前提条件

完成入门指南

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

如果您正在处理与 GDPR 相关的要求，请参阅IAB 要求对欧盟地区用户意见征求消息的影响

创建消息类型

在您的 AdMob 账号的隐私权和消息标签页下，使用可用的用户消息类型创建用户消息。UMP SDK 会尝试显示通过您项目中设置的 AdMob 应用 ID 创建的用户消息。如果没有为您的应用配置消息，SDK 将返回错误。

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

安装 SDK

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

如需查看使用更新循环轮询（而不是完成回调）检查完成情况的示例，请参阅上文。

根据需要加载并显示用户意见征求表单

收到最新的同意情况后，请对ConsentInfo 类调用LoadAndShowConsentFormIfRequired() 以加载用户意见征求表单。如果需要用户意见状态，SDK 会加载一个表单，并通过提供的 FormParent立即显示该表单。在用户关闭表单后，系统会调用 Future 已完成。如果不需要征得用户同意，系统会立即 Future 完成。

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()征得用户同意。在征求用户意见时，有两个位置可供检查：

在当前会话中收集用户意见后。
调用 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;
      }
    }
  }
}

隐私设置选项

有些用户意见征求表单会要求用户随时修改同意情况。请根据需要按照以下步骤实现隐私权选项按钮。

要实现这一目标，需要完成以下步骤：

实现可触发隐私权选项表单的界面元素，例如应用的设置页面中的按钮。
LoadAndShowConsentFormIfRequired() 完成后，请检查getPrivacyOptionsRequirementStatus() 以确定是否显示可呈现隐私权选项表单的界面元素。
当用户与您的界面元素交互时，调用showPrivacyOptionsForm() 以显示该表单，以便用户能够随时更新其隐私选项。

测试

如果您希望在开发过程中测试应用中的集成，请按照以下步骤以编程方式注册测试设备。在发布应用之前，请务必移除设置这些测试设备 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测试应用的行为，就如同设备位于欧洲经济区 (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();