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.
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.
},
)
載入並顯示隱私權訊息表單
收到最新的同意聲明狀態後,請呼叫
loadAndShowConsentFormIfRequired()
,載入收集使用者同意聲明所需的表單。載入後,表單會立即顯示。
Java
UserMessagingPlatform.loadAndShowConsentFormIfRequired(
activity,
formError -> {
// Consent gathering process is complete.
});
Kotlin
UserMessagingPlatform.loadAndShowConsentFormIfRequired(activity) { formError ->
// Consent gathering process is complete.
}
隱私權選項
部分隱私權訊息表單會透過發布商顯示的隱私權選項進入點呈現,讓使用者隨時管理隱私權選項。如要進一步瞭解使用者在隱私權選項進入點看到的訊息,請參閱「可用的使用者訊息類型」。
確認是否需要隱私權選項進入點
呼叫
requestConsentInfoUpdate()
後,請檢查
getPrivacyOptionsRequirementStatus()
,判斷應用程式是否需要隱私權選項進入點。如果需要,請在應用程式中新增可見且可互動的 UI 元素,顯示隱私權選項表單。如果不需要隱私權進入點,請將 UI 元素設為不可見且無法互動。
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
如需隱私權選項規定狀態的完整清單,請參閱
ConsentInformation.PrivacyOptionsRequirementStatus
。
顯示隱私權選項表單
當使用者與元素互動時,顯示隱私權選項表單:
Java
UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener);
Kotlin
UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)
要求放送廣告並取得使用者同意聲明
要求放送廣告前,請使用
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。