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>
收集同意聲明
如要收集同意聲明,請完成下列步驟:
- 要求取得最新的使用者同意資訊。
- 視需要載入及呈現同意聲明表單。
要求同意資訊
您應在每次啟動應用程式時,使用
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 的程式碼。
- 歡迎致電
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 提供一種方法,可使用 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 BannerExample 和 Kotlin BannerExample。