瞭解詳情

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

必要條件

  • Android API 級別 21 以上

建立訊息類型

請在 AdMob 帳戶的「隱私權與訊息」分頁中，使用其中一種可用的使用者訊息類型建立使用者訊息。UMP SDK 會嘗試顯示根據專案中設定的 AdMob 應用程式 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

您可以在 AdMob 使用者介面中找到應用程式 ID。使用下列程式碼片段，將 ID 新增至 AndroidManifest.xml：

<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));
GoogleMobileAdsConsentManager.java

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)
  },
)
GoogleMobileAdsConsentManager.kt

隱私權選項

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

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

呼叫 requestConsentInfoUpdate() 後，請查看 getPrivacyOptionsRequirementStatus()，判斷應用程式是否需要隱私權選項進入點：

Java


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

GoogleMobileAdsConsentManager.java

Kotlin


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

GoogleMobileAdsConsentManager.kt

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

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

Java


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

Kotlin


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

顯示隱私權選項表單

當使用者與元素互動時，請顯示隱私權選項表單：

Java


UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener);
GoogleMobileAdsConsentManager.java

Kotlin


UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)
GoogleMobileAdsConsentManager.kt

請求廣告

在應用程式中要求廣告前，請確認您是否已使用 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();
}

MyActivity.java

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()
    }
  }
}

MainActivity.kt

測試

如果您想在開發時測試應用程式中的整合功能，請按照下列步驟以程式輔助方式註冊測試裝置。發布應用程式之前，請務必移除用來設定這些測試裝置 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 提供一種方法，可使用 setDebugGeography() 測試應用程式的行為，就像是該裝置位於歐洲經濟區或英國一般。請注意，偵錯設定只適用於測試裝置。

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 BannerExample 和 Kotlin BannerExample。