瞭解詳情

Google User Messaging Platform (UMP) SDK 是隱私權和訊息工具,可協助您管理隱私權選項。詳情請參閱「關於隱私權與訊息」一文。

必要條件

  • Android API 級別 21 以上

建立訊息類型

透過 Ad Manager 帳戶的「隱私權與訊息」分頁,使用其中一種可用的使用者訊息類型建立使用者訊息。UMP SDK 會嘗試顯示從專案中 Ad Manager 應用程式 ID 設定建立的隱私權訊息。

詳情請參閱隱私權和訊息功能簡介

使用 Gradle 進行安裝

將 Google User Messaging Platform SDK 的依附元件新增至模組的應用程式層級 Gradle 檔案,通常為 app/build.gradle

dependencies {
  implementation("com.google.android.ump:user-messaging-platform:3.1.0")
}

變更應用程式的 build.gradle 後,請務必將專案與 Gradle 檔案保持同步。

新增應用程式 ID

您可以在 Ad Manager 使用者介面中找到應用程式 ID。使用以下程式碼片段,在 AndroidManifest.xml 中新增 ID:

<manifest>
  <application>
    <meta-data
        android:name="com.google.android.gms.ads.APPLICATION_ID"
        android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"/>
  </application>
</manifest>

如要收集同意聲明,請完成下列步驟:

  1. 要求取得最新的使用者同意資訊。
  2. 視需要載入及呈現同意聲明表單。

您應在每次啟動應用程式時,使用 requestConsentInfoUpdate() 要求更新使用者的同意聲明資訊。這項要求會檢查下列項目:

  • 是否需要取得同意聲明。例如,首次使用時需要取得同意聲明,或是先前的同意聲明已過期。
  • 是否需提供隱私權選項進入點。有些隱私權訊息會要求應用程式讓使用者隨時修改隱私權選項。

載入並顯示隱私權訊息表單 (如有需要)

收到最新的同意聲明狀態後,請呼叫 loadAndShowConsentFormIfRequired() 來載入收集使用者同意聲明所需的任何表單。載入後,表單會立即顯示。

以下程式碼示範如何要求使用者的最新同意聲明資訊。如有需要,程式碼會載入並顯示隱私權訊息表單:

Java


// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
    activity,
    params,
    () ->
        UserMessagingPlatform.loadAndShowConsentFormIfRequired(
            activity,
            formError -> {
              // Consent has been gathered.
              onConsentGatheringCompleteListener.consentGatheringComplete(formError);
            }),
    requestConsentError ->
        onConsentGatheringCompleteListener.consentGatheringComplete(requestConsentError));

Kotlin


// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
  activity,
  params,
  {
    UserMessagingPlatform.loadAndShowConsentFormIfRequired(activity) { formError ->
      // Consent has been gathered.
      onConsentGatheringCompleteListener.consentGatheringComplete(formError)
    }
  },
  { requestConsentError ->
    onConsentGatheringCompleteListener.consentGatheringComplete(requestConsentError)
  },
)

隱私權選項

部分隱私權訊息表單會透過發布商算繪的隱私權選項進入點顯示,讓使用者隨時管理隱私權選項。如要進一步瞭解使用者在隱私權選項入口處看到的訊息,請參閱「可用的使用者訊息類型」。

檢查是否需要設定隱私權選項進入點

呼叫 requestConsentInfoUpdate() 後,請檢查 ConsentInformation.PivacyOptionsRequirementStatus,判斷應用程式是否需要隱私權選項進入點:

Java


/** Helper variable to determine if the privacy options form is required. */
public boolean isPrivacyOptionsRequired() {
  return consentInformation.getPrivacyOptionsRequirementStatus()
      == PrivacyOptionsRequirementStatus.REQUIRED;
}

Kotlin


/** Helper variable to determine if the privacy options form is required. */
val isPrivacyOptionsRequired: Boolean
  get() =
    consentInformation.privacyOptionsRequirementStatus ==
      ConsentInformation.PrivacyOptionsRequirementStatus.REQUIRED

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

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

Java


if (googleMobileAdsConsentManager.isPrivacyOptionsRequired()) {
  // Regenerate the options menu to include a privacy setting.
  invalidateOptionsMenu();
}

Kotlin


if (googleMobileAdsConsentManager.isPrivacyOptionsRequired) {
  // Regenerate the options menu to include a privacy setting.
  invalidateOptionsMenu()
}

顯示隱私權選項表單

當使用者與元素互動時,系統會顯示隱私權選項表單:

Java


UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener);

Kotlin


UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)

請求廣告

在應用程式中要求廣告前,請確認您是否已使用 canRequestAds() 取得使用者的同意。收集同意聲明時,您可以檢查兩個位置:

  • 在目前的工作階段中收集到同意聲明後。
  • 呼叫 requestConsentInfoUpdate() 後立即執行。您可能已在上一個工作階段取得同意聲明。延遲時間最佳做法是,建議您不要等待回呼完成,這樣就能在應用程式啟動後盡快開始載入廣告。

如果在收集同意聲明的過程中發生錯誤,您仍應檢查是否能要求廣告。UMP SDK 會使用上一個工作階段的同意聲明狀態。

下列程式碼會檢查是否能在同意聲明收集過程中請求廣告:

Java


googleMobileAdsConsentManager.gatherConsent(
    this,
    consentError -> {
      if (consentError != null) {
        // Consent not obtained in current session.
        Log.w(
            TAG,
            String.format("%s: %s", consentError.getErrorCode(), consentError.getMessage()));
      }

      if (googleMobileAdsConsentManager.canRequestAds()) {
        initializeMobileAdsSdk();
      }
      // ...
    });

// This sample attempts to load ads using consent obtained in the previous session.
if (googleMobileAdsConsentManager.canRequestAds()) {
  initializeMobileAdsSdk();
}

Kotlin


googleMobileAdsConsentManager.gatherConsent(this) { error ->
  if (error != null) {
    // Consent not obtained in current session.
    Log.d(TAG, "${error.errorCode}: ${error.message}")
  }

  if (googleMobileAdsConsentManager.canRequestAds) {
    initializeMobileAdsSdk()
  }
  // ...
}

// This sample attempts to load ads using consent obtained in the previous session.
if (googleMobileAdsConsentManager.canRequestAds) {
  initializeMobileAdsSdk()
}

以下程式碼會在收集使用者同意聲明後,設定 Google Mobile Ads SDK:

Java


private void initializeMobileAdsSdk() {
  if (isMobileAdsInitializeCalled.getAndSet(true)) {
    return;
  }
  new Thread(
          () -> {
            // Initialize the Google Mobile Ads SDK on a background thread.
            MobileAds.initialize(this, initializationStatus -> {});

            // Load an ad on the main thread.
            runOnUiThread(this::loadBanner);
          })
      .start();
}

Kotlin


private fun initializeMobileAdsSdk() {
  if (isMobileAdsInitializeCalled.getAndSet(true)) {
    return
  }
  CoroutineScope(Dispatchers.IO).launch {
    // Initialize the Google Mobile Ads SDK on a background thread.
    MobileAds.initialize(this@MainActivity) {}

    runOnUiThread {
      // Load an ad on the main thread.
      loadBanner()
    }
  }
}

測試

如果您想在開發時測試應用程式中的整合功能,請按照下列步驟以程式輔助方式註冊測試裝置。發布應用程式之前,請務必移除用來設定這些測試裝置 ID 的程式碼。

  1. 歡迎致電 requestConsentInfoUpdate()
  2. 檢查記錄輸出內容,找出類似下列範例的訊息,其中會顯示裝置 ID 和如何將其新增為測試裝置:

    Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("33BE2250B43518CCDA7DE426D04EE231") to set this as a debug device.
    
  3. 將測試裝置 ID 複製到剪貼簿。

  4. 修改程式碼以呼叫 ConsentDebugSettings.Builder().TestDeviceHashedIds,並傳入測試裝置 ID 清單。

    Java

    ConsentDebugSettings debugSettings = new ConsentDebugSettings.Builder(this)
        .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
        .build();
    
    ConsentRequestParameters params = new ConsentRequestParameters
        .Builder()
        .setConsentDebugSettings(debugSettings)
        .build();
    
    consentInformation = UserMessagingPlatform.getConsentInformation(this);
    // Include the ConsentRequestParameters in your consent request.
    consentInformation.requestConsentInfoUpdate(
        this,
        params,
        // ...
    );
    

    Kotlin

    val debugSettings = ConsentDebugSettings.Builder(this)
        .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
        .build()
    
    val params = ConsentRequestParameters
        .Builder()
        .setConsentDebugSettings(debugSettings)
        .build()
    
    consentInformation = UserMessagingPlatform.getConsentInformation(this)
    // Include the ConsentRequestParameters in your consent request.
    consentInformation.requestConsentInfoUpdate(
        this,
        params,
        // ...
    )
    

強迫一個地理

UMP SDK 提供一種方法,可使用 DebugGeography 測試應用程式的行為,就像該裝置位於歐洲經濟區或英國境內一樣。請注意,偵錯設定只適用於測試裝置。

Java

ConsentDebugSettings debugSettings = new ConsentDebugSettings.Builder(this)
    .setDebugGeography(ConsentDebugSettings.DebugGeography.DEBUG_GEOGRAPHY_EEA)
    .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
    .build();

ConsentRequestParameters params = new ConsentRequestParameters
    .Builder()
    .setConsentDebugSettings(debugSettings)
    .build();

consentInformation = UserMessagingPlatform.getConsentInformation(this);
// Include the ConsentRequestParameters in your consent request.
consentInformation.requestConsentInfoUpdate(
    this,
    params,
    ...
);

Kotlin

val debugSettings = ConsentDebugSettings.Builder(this)
    .setDebugGeography(ConsentDebugSettings.DebugGeography.DEBUG_GEOGRAPHY_EEA)
    .addTestDeviceHashedId("TEST-DEVICE-HASHED-ID")
    .build()

val params = ConsentRequestParameters
    .Builder()
    .setConsentDebugSettings(debugSettings)
    .build()

consentInformation = UserMessagingPlatform.getConsentInformation(this)
// Include the ConsentRequestParameters in your consent request.
consentInformation.requestConsentInfoUpdate(
    this,
    params,
    ...
)

使用 UMP SDK 測試應用程式時,建議您重設 SDK 狀態,以模擬使用者初次安裝的體驗。方法是使用 SDK 提供的 reset() 方法。

Java

consentInformation.reset();

Kotlin

consentInformation.reset()

GitHub 上的範例

如需本頁所述 UMP SDK 整合功能的完整範例,請參閱 Java BannerExampleKotlin BannerExample