如要討論產品並提供意見，請加入 Google 廣告與評估社群伺服器中的官方 AdMob Discord 頻道。

本頁面由 Cloud Translation API 翻譯而成。

開始使用

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>

取得使用者的同意聲明資訊

如要取得使用者的同意聲明資訊，請按照下列步驟操作：

宣告 ConsentInformation 的例項：

Java

private final ConsentInformation consentInformation;

Kotlin

private lateinit val consentInformation: ConsentInformation

初始化 ConsentInformation 執行個體：

Java

consentInformation = UserMessagingPlatform.getConsentInformation(context);

Kotlin

consentInformation = UserMessagingPlatform.getConsentInformation(context)

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

是否需要同意聲明。舉例來說，您是第一次要求同意聲明，或是先前的同意聲明決定已過期。
是否需要隱私權選項進入點。部分隱私權訊息會要求應用程式允許使用者隨時修改隱私權選項。

Java


// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
    activity,
    params,
    () -> // Called when consent information is successfully updated.
    requestConsentError -> // Called when there's an error updating consent information.GoogleMobileAdsConsentManager.java

Kotlin


// Requesting an update to consent information should be called on every app launch.
consentInformation.requestConsentInfoUpdate(
  activity,
  params,
  {
    // Called when consent information is successfully updated.
  },
  { requestConsentError ->
    // Called when there's an error updating consent information.
  },
)GoogleMobileAdsConsentManager.kt

載入並顯示隱私權訊息表單

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

Java


UserMessagingPlatform.loadAndShowConsentFormIfRequired(
    activity,
    formError -> {
      // Consent gathering process is complete.
    });GoogleMobileAdsConsentManager.java

Kotlin


UserMessagingPlatform.loadAndShowConsentFormIfRequired(activity) { formError ->
  // Consent gathering process is complete.
}GoogleMobileAdsConsentManager.kt

隱私權選項

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

確認是否需要隱私權選項進入點

呼叫 requestConsentInfoUpdate() 後，請檢查 getPrivacyOptionsRequirementStatus()，判斷應用程式是否需要隱私權選項進入點。如果需要，請在應用程式中新增可見且可互動的 UI 元素，顯示隱私權選項表單。如果不需要隱私權進入點，請將 UI 元素設為不可見且無法互動。

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

如需隱私權選項規定狀態的完整清單，請參閱 ConsentInformation.PrivacyOptionsRequirementStatus。

顯示隱私權選項表單

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

Java


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

Kotlin


UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)GoogleMobileAdsConsentManager.kt

要求放送廣告並取得使用者同意聲明

要求放送廣告前，請使用 canRequestAds() 檢查是否已取得使用者同意聲明：

Java

consentInformation.canRequestAds();

Kotlin

consentInformation.canRequestAds()

收集同意聲明時，請檢查下列位置是否可以要求廣告：

在目前工作階段中，UMP SDK 收集同意聲明後。
呼叫 requestConsentInfoUpdate() 後立即執行。UMP SDK 可能已在上一個應用程式工作階段中取得同意聲明。

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

避免重複的廣告請求作業

在收集同意聲明和呼叫 requestConsentInfoUpdate() 後檢查 canRequestAds() 時，請確保您的邏輯可防止多餘的廣告請求，以免兩項檢查都傳回 true。舉例來說，使用布林變數。

測試

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

歡迎致電requestConsentInfoUpdate()。
檢查記錄輸出內容，尋找類似以下範例的訊息，其中會顯示裝置 ID，以及如何將裝置新增為測試裝置：
```
Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("33BE2250B43518CCDA7DE426D04EE231") to set this as a debug device.
```
將測試裝置 ID 複製到剪貼簿。

修改程式碼，呼叫 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。