Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

设置 UMP SDK

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

创建消息类型

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

获取用户的意见征求信息

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

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

/**
 * Requests consent information update on app launch.
 */
export function requestConsent(onComplete?: () => void) {
  requestConsentInfoUpdate({}, (error) => {
    if (error) {
      console.warn('Consent info update error:', error.message);
    } else {
      console.log('Consent info update complete.');
    }

    // Load and show consent form if required.
    loadAndPresentConsentForm(onComplete);
  });
}

加载并显示隐私权消息表单

收到最新的用户同意情况后，请调用 loadAndShowConsentFormIfRequired() 来加载征求用户同意所需的任何表单。加载后，表单会立即显示。

/**
 * Loads and presents the privacy message form if required to collect user consent.
 */
export function loadAndPresentConsentForm(onComplete?: () => void) {
  loadAndShowConsentFormIfRequired((formError) => {
    if (formError) {
      console.warn('Consent form error:', formError.message);
    } else {
      console.log('Consent gathering complete.');
    }

    // Execute logic that depends on consent state (for example, initialize the SDK).
    onComplete?.();
  });
}

隐私设置选项

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

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

调用 requestConsentInfoUpdate() 后，请检查 getPrivacyOptionsRequirementStatus()，以确定您的应用是否需要隐私选项入口点。如果需要入口点，请向应用添加一个可见且可互动的界面元素，用于呈现隐私选项表单。如果不需要隐私权入口点，请将界面元素配置为不可见且不可交互。

/**
 * Helper to determine if the privacy options entry point is required.
 */
export function isPrivacyOptionsRequired(): boolean {
  return (
    getPrivacyOptionsRequirementStatus() ===
    PrivacyOptionsRequirementStatus.REQUIRED
  );
}

如需查看隐私选项要求状态的完整列表，请参阅 PrivacyOptionsRequirementStatus。

显示隐私选项表单

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

/**
 * Renders a privacy options button if required by user consent policy.
 */
export function PrivacyOptionsButton({
  onDismissed,
}: {
  onDismissed?: (error?: FormError) => void;
}) {
  const isRequired =
    getPrivacyOptionsRequirementStatus() ===
    PrivacyOptionsRequirementStatus.REQUIRED;

  if (!isRequired) {
    return null;
  }

  const handleShowPrivacyOptions = () => {
    showPrivacyOptionsForm((error) => {
      if (error) {
        console.error('Failed to show privacy options form:', error.message);
      } else {
        console.log('Privacy options form dismissed.');
      }

      // Execute custom logic after form is dismissed.
      onDismissed?.(error);
    });
  };

  return <Button title="Privacy Settings" onPress={handleShowPrivacyOptions} />;
}

在征得用户同意的情况下请求广告

在请求广告之前，请使用 canRequestAds() 检查您是否已征得用户同意：

/**
 * Checks whether user consent allows requesting ads and initializes the SDK.
 */
let isMobileAdsInitialized = false;

export function initializeMobileAdsSdkIfConsentGiven() {
  if (canRequestAds()) {
    if (!isMobileAdsInitialized) {
      isMobileAdsInitialized = true;
      initialize({}, (status) => {
        console.log('Google Mobile Ads SDK initialized:', status);
      });
    }
  }
}

下面列出了在征求用户同意时可以检查是否可以请求广告的位置：

UMP SDK 在当前会话中征求用户同意后。
在您调用 requestConsentInfoUpdate() 后立即调用。UMP SDK 可能已在之前的应用会话中征得用户同意。

如果征求用户意见的过程中出现错误，请检查您是否可以请求广告。UMP SDK 会使用上一个应用会话中的用户同意情况。

防止重复的广告请求工作

在征求用户同意后以及调用 requestConsentInfoUpdate() 后，您需要检查 canRequestAds()，请确保您的逻辑可防止可能导致两次检查都返回 true 的冗余广告请求。例如，使用布尔值变量。

测试

如果您希望在应用开发过程中测试集成，请按照以下步骤以编程方式注册您的测试设备。在发布应用之前，请务必移除用于设置这些测试设备 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 复制到剪贴板。

修改代码，以便调用 consentDebugSettings.testDeviceIdentifiers 并传入您的测试设备 ID 列表。

/**
 * Registers a test device for testing consent flows.
 */
export function configureTestDevice() {
  requestConsentInfoUpdate(
    {
      consentDebugSettings: {
        debugGeography: DebugGeography.DISABLED,
        testDeviceIdentifiers: ["TEST_DEVICE_HASHED_ID"],
      },
    },
    (error) => {
      if (!error) {
        console.log('Test device registered.');
      }
    },
  );
}

强制调试地理位置

UMP SDK 提供了一种方法：使用 DebugGeography 测试您的应用行为，就像设备位于欧洲经济区 (EEA)、英国 (UK) 和瑞士等各个地区一样。请注意，调试设置仅适用于测试设备。

/**
 * Configures debug settings to force EEA geography on a test device.
 */
export function configureDebugGeography() {
  requestConsentInfoUpdate(
    {
      consentDebugSettings: {
        debugGeography: DebugGeography.EEA,
        testDeviceIdentifiers: ["TEST_DEVICE_HASHED_ID"],
      },
    },
    (error) => {
      if (!error) {
        console.log('Consent debug test configuration loaded.');
      }
    },
  );
}

重置用户同意情况

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

/**
 * Resets consent state for testing purposes.
 */
export function resetConsentState() {
  reset();
}