Google User Messaging Platform (UMP) SDK 是一項隱私權與訊息工具, 協助您管理隱私權選擇若需更多資訊,請參閲 關於隱私權與訊息。
必要條件
- Android API 級別 21 以上
建立訊息類型
使用以下其中一則文字建立使用者訊息: 可用的使用者訊息類型 中,隱私權與訊息分頁 AdMob 讓他們使用服務帳戶UMP SDK 會嘗試顯示 從應用程式 ID AdMob 建立的隱私權訊息 您在專案中設定的內容
詳情請參閱 關於隱私權與訊息。
使用 Gradle 安裝
將 Google User Messaging Platform SDK 的依附元件新增到模組的
應用程式層級的 Gradle 檔案,通常為 app/build.gradle
:
dependencies {
implementation("com.google.android.ump:user-messaging-platform:3.0.0")
}
變更應用程式的build.gradle
後,請務必同步處理
存取 Gradle 檔案的專案。
新增應用程式 ID
您可以在「
AdMob UI:
使用下列程式碼片段,將 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>
要求同意聲明資訊
在每個應用程式中,應要求使用者更新同意聲明資訊
使用 requestConsentInfoUpdate()
啟動。這項要求會檢查
包括:
- 是否必須取得同意聲明。舉例來說, 或先前的同意聲明決定失效
- 是否需提供隱私權選項進入點。部分隱私權訊息 應用程式必須允許使用者隨時修改隱私權選項。
以下範例說明如何從 MainActivity
onCreate()
方法。
Java
package com.example.myapplication;
import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;
import com.google.android.ump.ConsentInformation;
import com.google.android.ump.ConsentRequestParameters;
import com.google.android.ump.FormError;
import com.google.android.ump.UserMessagingPlatform;
public class MainActivity extends AppCompatActivity {
private ConsentInformation consentInformation;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
// Create a ConsentRequestParameters object.
ConsentRequestParameters params = new ConsentRequestParameters
.Builder()
.build();
consentInformation = UserMessagingPlatform.getConsentInformation(this);
consentInformation.requestConsentInfoUpdate(
this,
params,
(OnConsentInfoUpdateSuccessListener) () -> {
// TODO: Load and show the privacy message form.
},
(OnConsentInfoUpdateFailureListener) requestConsentError -> {
// Consent gathering failed.
Log.w(TAG, String.format("%s: %s",
requestConsentError.getErrorCode(),
requestConsentError.getMessage()));
});
}
}
Kotlin
package com.example.myapplication
import com.google.android.ump.ConsentInformation
import com.google.android.ump.ConsentInformation.OnConsentInfoUpdateFailureListener
import com.google.android.ump.ConsentInformation.OnConsentInfoUpdateSuccessListener
import com.google.android.ump.ConsentRequestParameters
import com.google.android.ump.UserMessagingPlatform
class MainActivity : AppCompatActivity() {
private lateinit var consentInformation: ConsentInformation
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
// Create a ConsentRequestParameters object.
val params = ConsentRequestParameters
.Builder()
.build()
consentInformation = UserMessagingPlatform.getConsentInformation(this)
consentInformation.requestConsentInfoUpdate(
this,
params,
ConsentInformation.OnConsentInfoUpdateSuccessListener {
// TODO: Load and show the privacy message form.
},
ConsentInformation.OnConsentInfoUpdateFailureListener {
requestConsentError ->
// Consent gathering failed.
Log.w(TAG, "${requestConsentError.errorCode}: ${requestConsentError.message}")
})
}
}
視需要載入並顯示隱私權訊息表單
收到最新的同意聲明狀態後,請致電
loadAndShowConsentFormIfRequired()
即可載入任何必要的表單,
收集使用者同意聲明表單載入後會立即顯示。
Java
public class MainActivity extends AppCompatActivity {
private ConsentInformation consentInformation;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
// Create a ConsentRequestParameters object.
ConsentRequestParameters params = new ConsentRequestParameters
.Builder()
.build();
consentInformation = UserMessagingPlatform.getConsentInformation(this);
consentInformation.requestConsentInfoUpdate(
this,
params,
(OnConsentInfoUpdateSuccessListener) () -> {
UserMessagingPlatform.loadAndShowConsentFormIfRequired(
this,
(OnConsentFormDismissedListener) loadAndShowError -> {
if (loadAndShowError != null) {
// Consent gathering failed.
Log.w(TAG, String.format("%s: %s",
loadAndShowError.getErrorCode(),
loadAndShowError.getMessage()));
}
// Consent has been gathered.
}
);
},
(OnConsentInfoUpdateFailureListener) requestConsentError -> {
// Consent gathering failed.
Log.w(TAG, String.format("%s: %s",
requestConsentError.getErrorCode(),
requestConsentError.getMessage()));
});
}
}
Kotlin
class MainActivity : AppCompatActivity() {
private lateinit var consentInformation: ConsentInformation
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
// Create a ConsentRequestParameters object.
val params = ConsentRequestParameters
.Builder()
.build()
consentInformation = UserMessagingPlatform.getConsentInformation(this)
consentInformation.requestConsentInfoUpdate(
this,
params,
ConsentInformation.OnConsentInfoUpdateSuccessListener {
UserMessagingPlatform.loadAndShowConsentFormIfRequired(
this@MainActivity,
ConsentForm.OnConsentFormDismissedListener {
loadAndShowError ->
if (loadAndShowError != null) {
// Consent gathering failed.
Log.w(TAG, "${loadAndShowError.errorCode}: ${loadAndShowError.message}")
}
// Consent has been gathered.
}
)
},
ConsentInformation.OnConsentInfoUpdateFailureListener {
requestConsentError ->
// Consent gathering failed.
Log.w(TAG, "${requestConsentError.errorCode}: ${requestConsentError.message}")
})
}
}
您需要在使用者做出選擇或關閉廣告後執行任何動作 請將該邏輯放在 callback中 。
隱私權選項
部分隱私權訊息表單是由發布商顯示的隱私權提供 選項進入點,讓使用者隨時管理自己的隱私權選項。 如要進一步瞭解使用者會看到哪些訊息,請透過隱私權選項 進入點,請參閱 可用的使用者訊息類型:
如要實作隱私權選項進入點,請完成下列步驟:
- 請檢查
ConsentInformation.PrivacyOptionsRequirementStatus
。 - 如果隱私權選項進入點 您必須在應用程式中加入可見且可互動的 UI 元素。
- 使用以下程式碼觸發隱私權選項表單:
showPrivacyOptionsForm()
。
以下程式碼範例會示範這些步驟:
Java
private final ConsentInformation consentInformation;
// Show a privacy options button if required.
public boolean isPrivacyOptionsRequired() {
return consentInformation.getPrivacyOptionsRequirementStatus()
== PrivacyOptionsRequirementStatus.REQUIRED;
}
@Override
protected void onCreate(Bundle savedInstanceState) {
// ...
consentInformation = UserMessagingPlatform.getConsentInformation(this);
consentInformation.requestConsentInfoUpdate(
this,
params,
(OnConsentInfoUpdateSuccessListener) () -> {
UserMessagingPlatform.loadAndShowConsentFormIfRequired(
this,
(OnConsentFormDismissedListener) loadAndShowError -> {
// ...
// Consent has been gathered.
if (isPrivacyOptionsRequired()) {
// Regenerate the options menu to include a privacy setting.
invalidateOptionsMenu();
}
}
)
}
// ...
}
@Override
public boolean onCreateOptionsMenu(Menu menu) {
getMenuInflater().inflate(R.menu.action_menu, menu);
MenuItem moreMenu = menu.findItem(R.id.action_more);
moreMenu.setVisible(isPrivacyOptionsRequired());
return true;
}
@Override
public boolean onOptionsItemSelected(MenuItem item) {
// ...
popup.setOnMenuItemClickListener(
popupMenuItem -> {
if (popupMenuItem.getItemId() == R.id.privacy_settings) {
// Present the privacy options form when a user interacts with
// the privacy settings button.
UserMessagingPlatform.showPrivacyOptionsForm(
this,
formError -> {
if (formError != null) {
// Handle the error.
}
}
);
return true;
}
return false;
});
return super.onOptionsItemSelected(item);
}
Kotlin
private val consentInformation: ConsentInformation =
UserMessagingPlatform.getConsentInformation(context)
// Show a privacy options button if required.
val isPrivacyOptionsRequired: Boolean
get() =
consentInformation.privacyOptionsRequirementStatus ==
ConsentInformation.PrivacyOptionsRequirementStatus.REQUIRED
override fun onCreate(savedInstanceState: Bundle?) {
// ...
consentInformation = UserMessagingPlatform.getConsentInformation(this)
consentInformation.requestConsentInfoUpdate(
this,
params,
ConsentInformation.OnConsentInfoUpdateSuccessListener {
UserMessagingPlatform.loadAndShowConsentFormIfRequired(
this@MainActivity,
ConsentForm.OnConsentFormDismissedListener {
// ...
// Consent has been gathered.
if (isPrivacyOptionsRequired) {
// Regenerate the options menu to include a privacy setting.
invalidateOptionsMenu();
}
}
)
}
// ...
}
override fun onCreateOptionsMenu(menu: Menu?): Boolean {
menuInflater.inflate(R.menu.action_menu, menu)
menu?.findItem(R.id.action_more)?.apply {
isVisible = isPrivacyOptionsRequired
}
return super.onCreateOptionsMenu(menu)
}
override fun onOptionsItemSelected(item: MenuItem): Boolean {
// ...
popup.setOnMenuItemClickListener { popupMenuItem ->
when (popupMenuItem.itemId) {
R.id.privacy_settings -> {
// Present the privacy options form when a user interacts with
// the privacy settings button.
UserMessagingPlatform.showPrivacyOptionsForm(this) { formError ->
formError?.let {
// Handle the error.
}
}
true
}
else -> false
}
}
return super.onOptionsItemSelected(item)
}
請求廣告
在應用程式中請求廣告前,請確認您已取得同意聲明
透過 canRequestAds()
存取。這裡共有兩個
收集同意聲明時的檢查地點:
- 在目前的工作階段中收集到同意聲明後。
- 呼叫
requestConsentInfoUpdate()
後立即執行。 您可能已在上一個工作階段取得同意聲明。一段延遲時間 最佳做法,建議您不要等待回呼完成 在應用程式啟動後盡快載入廣告。
如果在收集同意聲明的過程中發生錯誤, 請求廣告UMP SDK 會使用上一個 會很有幫助
Java
public class MainActivity extends AppCompatActivity {
private ConsentInformation consentInformation;
// Use an atomic boolean to initialize the Google Mobile Ads SDK and load ads once.
private final AtomicBoolean isMobileAdsInitializeCalled = new AtomicBoolean(false);
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
// Create a ConsentRequestParameters object.
ConsentRequestParameters params = new ConsentRequestParameters
.Builder()
.build();
consentInformation = UserMessagingPlatform.getConsentInformation(this);
consentInformation.requestConsentInfoUpdate(
this,
params,
(OnConsentInfoUpdateSuccessListener) () -> {
UserMessagingPlatform.loadAndShowConsentFormIfRequired(
this,
(OnConsentFormDismissedListener) loadAndShowError -> {
if (loadAndShowError != null) {
// Consent gathering failed.
Log.w(TAG, String.format("%s: %s",
loadAndShowError.getErrorCode(),
loadAndShowError.getMessage()));
}
// Consent has been gathered.
if (consentInformation.canRequestAds()) {
initializeMobileAdsSdk();
}
}
);
},
(OnConsentInfoUpdateFailureListener) requestConsentError -> {
// Consent gathering failed.
Log.w(TAG, String.format("%s: %s",
requestConsentError.getErrorCode(),
requestConsentError.getMessage()));
});
// Check if you can initialize the Google Mobile Ads SDK in parallel
// while checking for new consent information. Consent obtained in
// the previous session can be used to request ads.
if (consentInformation.canRequestAds()) {
initializeMobileAdsSdk();
}
}
private void initializeMobileAdsSdk() {
if (isMobileAdsInitializeCalled.getAndSet(true)) {
return;
}
new Thread(
() -> {
// Initialize the Google Mobile Ads SDK on a background thread.
MobileAds.initialize(this, initializationStatus -> {});
runOnUiThread(
() -> {
// TODO: Request an ad.
// loadInterstitialAd();
});
})
.start();
}
}
Kotlin
class MainActivity : AppCompatActivity() {
private lateinit var consentInformation: ConsentInformation
// Use an atomic boolean to initialize the Google Mobile Ads SDK and load ads once.
private var isMobileAdsInitializeCalled = AtomicBoolean(false)
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
// Create a ConsentRequestParameters object.
val params = ConsentRequestParameters
.Builder()
.build()
consentInformation = UserMessagingPlatform.getConsentInformation(this)
consentInformation.requestConsentInfoUpdate(
this,
params,
ConsentInformation.OnConsentInfoUpdateSuccessListener {
UserMessagingPlatform.loadAndShowConsentFormIfRequired(
this@MainActivity,
ConsentForm.OnConsentFormDismissedListener {
loadAndShowError ->
if (loadAndShowError != null) {
// Consent gathering failed.
Log.w(TAG, "${loadAndShowError.errorCode}: ${loadAndShowError.message}")
}
// Consent has been gathered.
if (consentInformation.canRequestAds()) {
initializeMobileAdsSdk()
}
}
)
},
ConsentInformation.OnConsentInfoUpdateFailureListener {
requestConsentError ->
// Consent gathering failed.
Log.w(TAG, "${requestConsentError.errorCode}: ${requestConsentError.message}")
})
// Check if you can initialize the Google Mobile Ads SDK in parallel
// while checking for new consent information. Consent obtained in
// the previous session can be used to request ads.
if (consentInformation.canRequestAds()) {
initializeMobileAdsSdk()
}
}
private fun initializeMobileAdsSdk() {
if (isMobileAdsInitializeCalled.getAndSet(true)) {
return
}
val backgroundScope = CoroutineScope(Dispatchers.IO)
backgroundScope.launch {
MobileAds.initialize(this@MainActivity) {}
runOnUiThread {
// TODO: Request an ad.
// loadInterstitialAd()
}
}
}
}
測試
如要在開發過程中測試應用程式內整合功能,請按照下列步驟操作: 這些步驟以程式輔助方式註冊測試裝置。請務必移除 程式碼,在發布應用程式前設定測試裝置 ID。
- 呼叫
requestConsentInfoUpdate()
。 檢查記錄輸出內容,找出類似下列範例的訊息,其中會顯示裝置 ID 和如何將裝置新增為測試裝置:
Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("33BE2250B43518CCDA7DE426D04EE231") to set this as a debug device.
將測試裝置 ID 複製到剪貼簿。
修改程式碼以
ConsentDebugSettings.Builder().addTestDeviceHashedId()
並傳入 測試裝置 ID 清單。
強迫一個地理
UMP SDK 可讓您測試應用程式行為,就像測試裝置
地址在歐洲經濟區或英國境內,並使用 the setDebugGeography()
method which takes a DebugGeography
on ConsentDebugSettings.Builder
。請注意,
偵錯設定僅適用於測試裝置。
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()