開始使用

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;
}

在應用程式中新增可見元素

如果需要隱私權進入點，請在應用程式中新增可見且可互動的 UI 元素，以便顯示隱私權選項表單。如果不需要隱私權進入點，請將 UI 元素設為不可見且無法互動。

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 Mobile Ads 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 測試應用程式的行為，就像裝置位於歐洲經濟區或英國境內一般。請注意，偵錯設定只適用於測試裝置。

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 範例。