开始使用

根据 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

1. 按照相关步骤安装 Google 移动广告 (GMA) C++ SDK。UMP C++ SDK 包含在 GMA C++ SDK 中。

2. 请确保配置您的应用的 AdMob 应用 ID 然后再继续。

3. 在您的代码中，通过调用 ConsentInfo::GetInstance()。

   • 在 Android 上，您需要传入由 API 提供的 JNIEnv 和 Activity， NDK。您只需在首次调用 GetInstance() 时执行此操作。
   • 或者，如果您已在使用 Firebase C++ SDK，您可以通过 在 firebase::App 中GetInstance()。

   #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 实例：

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，并提供“last result”（上次结果）函数来检索 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>。

添加应用 ID

您可以在 AdMob 界面。 将此 ID 添加到您的 替换为以下代码段：

征求用户同意

您应该在每个应用中请求更新用户的用户意见征求信息 使用 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.
      }
    });
}

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

警告 ：使用其他方式检查用户同意情况，例如在您的 Google Ads 账号中 应用或之前保存的用户意见征求字符串，都可能会导致 TCF 3.3 错误（如果用户选择同意） 已过期。

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

获得最新的意见征求状态后，请调用 LoadAndShowConsentFormIfRequired() 在 ConsentInfo 类来加载用户意见征求表单。如果 必须提供用户同意情况，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.
          }
        });
      }
    });
}

在用户做出选择或忽略后您需要执行任何操作 表单，将该逻辑放在处理 Future 的代码中 由 LoadAndShowConsentFormIfRequired() 返回。

提出广告请求

在您的应用中发出广告请求之前，请检查您是否已征得用户同意 使用 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. 实现界面元素，例如应用的设置页面中的按钮； 可触发隐私权选项表单的应用
2. LoadAndShowConsentFormIfRequired() 完成后，请检查 getPrivacyOptionsRequirementStatus() 来确定是否展示 可显示隐私选项表单的界面元素。
3. 当用户与界面元素交互时，调用 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 提供了一种方法来测试应用行为，就好像设备被 位于欧洲经济区 (EEA) 或英国境内的用户使用 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 提供了 Reset() 方法。

  ConsentInfo::GetInstance()->Reset();

注意： 此方法仅用于测试目的。您 不应在正式版代码中调用 Reset() 。

GitHub 上的示例