开始使用

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

创建消息类型

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

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

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

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

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

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

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

收到最新的意见征求状态后，调用 loadAndShowConsentFormIfRequired() 以加载收集用户意见征求所需的所有表单。加载后，表单会立即显示。

以下代码演示了如何请求用户的最新意见征求信息。如有需要，该代码会加载并显示隐私权消息表单：

@override
void initState() {
  super.initState();

  // Create a ConsentRequestParameters object.
  final params = ConsentRequestParameters();

  // Request an update to consent information on every app launch.
  ConsentInformation.instance.requestConsentInfoUpdate(
    params,
    () async {
      ConsentForm.loadAndShowConsentFormIfRequired((loadAndShowError) {
        if (loadAndShowError != null) {
          // Consent gathering failed.
        }

        // Consent has been gathered.
      });
    },
    (FormError error) {
      // Handle the error.
    },
  );
}

隐私选项

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

检查是否需要隐私设置选项入口点

调用 requestConsentInfoUpdate() 后，请检查 getPrivacyOptionsRequirementStatus()，以确定您的应用是否需要隐私选项入口点：

/// Helper variable to determine if the privacy options entry point is required.
Future<bool> isPrivacyOptionsRequired() async {
  return await ConsentInformation.instance
      .getPrivacyOptionsRequirementStatus() ==
      PrivacyOptionsRequirementStatus.required;
}

向应用添加可见元素

如果需要隐私权入口点，请向应用添加一个可见且可交互的界面元素，用于显示隐私权选项表单。如果不需要隐私权入口点，请将界面元素配置为不可见且不可互动。

ConsentInformation.instance.requestConsentInfoUpdate(
  params,
  () async {
    ConsentForm.loadAndShowConsentFormIfRequired((loadAndShowError) {
      if (loadAndShowError != null) {
        // Consent gathering failed.
      }

      // Consent has been gathered.

      // Redraw the app bar actions if a privacy options entry point is required.
      if (await isPrivacyOptionsRequired()) {
        setState(() {
          _isPrivacyOptionsRequired = true;
        });
      }
    });
  },
  // ...

显示隐私选项表单

当用户与您的元素互动时，显示隐私选项表单：

ConsentForm.showPrivacyOptionsForm((formError) {
  if (formError != null) {
    debugPrint("${formError.errorCode}: ${formError.message}");
  }
});

提出广告请求

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

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

如果在征求用户同意的过程中发生错误，您仍应检查自己是否可以请求展示广告。UMP SDK 会使用上一个会话中的意见征求状态。

以下代码会检查您是否可以在征求用户意见的过程中请求展示广告：

ConsentInformation.instance.requestConsentInfoUpdate(
  params,
  () async {
    ConsentForm.loadAndShowConsentFormIfRequired((loadAndShowError) {
      if (loadAndShowError != null) {
        // Consent gathering failed.
      }

      // Consent has been gathered.
      if (await ConsentInformation.instance.canRequestAds()) {
        _initializeGoogleMobileAdsSDK()
      }
      // ...
    });
  },
  (FormError error) {},
);

// Check if you can initialize the Mobile Ads SDK in parallel while
// checking for new consent information. Consent obtained in the
// previous session can be used to request ads.
if (await ConsentInformation.instance.canRequestAds()) {
  _initializeGoogleMobileAdsSDK()
}

以下代码会在征得用户同意后设置 Google 移动广告 SDK：

void _initializeGoogleMobileAdsSDK() async {
  if (_isMobileAdsInitializeCalled) {
    return;
  }

  _isMobileAdsInitializeCalled = true;

  // Initialize the Mobile Ads SDK.
  MobileAds.instance.initialize();

  // Load an ad.
  _loadAd();
}

测试

如果您希望在应用开发过程中测试集成，请按照以下步骤以编程方式注册您的测试设备。在发布应用之前，请务必移除用于设置这些测试设备 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. 修改代码，以便调用 ConsentDebugSettings.testIdentifiers 并将其传入您的测试设备 ID 列表。

    ConsentDebugSettings debugSettings = ConsentDebugSettings(
  testIdentifiers: ["TEST-DEVICE-HASHED-ID"],
);

ConsentRequestParameters params =
    ConsentRequestParameters(consentDebugSettings: debugSettings);

ConsentInformation.instance.requestConsentInfoUpdate(params, () async {
  // ...
};

强制调试地理位置

UMP SDK 提供了一种方法：使用 debugGeography 测试您的应用行为，就像设备位于欧洲经济区 (EEA) 或英国境内一样。请注意，调试设置仅适用于测试设备。

ConsentDebugSettings debugSettings = ConsentDebugSettings(
  debugGeography: DebugGeography.debugGeographyEea,
  testIdentifiers: ["TEST-DEVICE-HASHED-ID"],
);

ConsentRequestParameters params =
    ConsentRequestParameters(consentDebugSettings: debugSettings);

ConsentInformation.instance.requestConsentInfoUpdate(params, () async {
  // ...
};

通过 UMP SDK 测试应用时，您可能会发现重置 SDK 的状态很实用，因为您可以模拟用户的首次安装体验。该 SDK 提供的 reset() 方法可实现此目的。

ConsentInformation.instance.reset();

GitHub 上的示例

如需查看本页介绍的 UMP SDK 集成的完整示例，请参阅 我们的 Flutter 示例。