分享您的意見,協助我們打造 Google Mobile Ads SDK 的藍圖。請在 2023 年 5 月 5 日以前完成 Google Mobile Ads SDK 2023 年年度問卷調查

開始使用

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

根據 Google 的《歐盟地區使用者同意授權政策》規定,您必須向英國和歐洲經濟區境內的使用者揭露特定資訊。另外,在法律要求的情況下,您必須取得使用者同意才能使用 Cookie 或其他本機儲存空間,並且使用個人資料 (例如 AdID) 放送廣告。本政策是配合《歐盟地區電子通訊隱私指令》和《一般資料保護規則》(GDPR) 而製定。

為了協助發布者根據這項政策履行自身職責,Google 提供了 User Messaging Platform (UMP) SDK。UMP SDK 已更新為支援最新的 IAB 標準以上所有設定現在都能輕鬆用於 AdMob 隱私權與訊息。

必要條件

使用者訊息類型

如需支援訊息的完整清單,請參閱 使用者訊息類型 如需實作各種訊息類型的特定操作說明,請參閱左側導覽列。

使用 Gradle 進行安裝

如果您使用的是 Google Mobile Ads SDK 19.8.0 或更新版本,則套件中會包含 UMP SDK。如果您使用的是舊版 Mobile Ads SDK,請在應用程式的 build.gradle 中加入 UMP SDK,如下所示:

dependencies {
    // This dependency is automatically included by Google Mobile Ads SDK 19.8.0
    // or higher.
    implementation 'com.google.android.ump:user-messaging-platform:2.0.0'
}

變更應用程式的 build.gradle 後,請務必將專案與 Gradle 檔案保持同步。

接著, 找出您的應用程式 ID 並將其新增至 AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.rewardedinterstitialexample">

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">
        <!-- Sample app ID: ca-app-pub-3940256099942544~3347511713 -->
        <meta-data
            android:name="com.google.android.gms.ads.APPLICATION_ID"
            android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"/>
        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>

</manifest>

判斷訊息是否需要顯示

每次啟動時,您都必須在載入表單前使用 requestConsentInfoUpdate() 要求更新使用者的同意聲明資訊。這可以決定使用者是否需要提供同意聲明 (如果尚未執行的話) 或同意聲明已過期。

在需要呈現表單時,請使用儲存在 consentInformation物件中的資訊。

以下範例說明如何檢查應用程式啟動時的狀態:

Java

package com.example.myapplication;

import androidx.appcompat.app.AppCompatActivity;

import android.os.Bundle;

import com.google.android.ump.ConsentForm;
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;
    private ConsentForm consentForm;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // Set tag for under age of consent. false means users are not under
        // age.
        ConsentRequestParameters params = new ConsentRequestParameters
            .Builder()
            .setTagForUnderAgeOfConsent(false)
            .build();

        consentInformation = UserMessagingPlatform.getConsentInformation(this);
        consentInformation.requestConsentInfoUpdate(
            this,
            params,
            new ConsentInformation.OnConsentInfoUpdateSuccessListener() {
                @Override
                public void onConsentInfoUpdateSuccess() {
                    // The consent information state was updated.
                    // You are now ready to check if a form is available.
                }
            },
            new ConsentInformation.OnConsentInfoUpdateFailureListener() {
                @Override
                public void onConsentInfoUpdateFailure(FormError formError) {
                    // Handle the error.
                }
            });
    }
}

Kotlin

Coming soon.

載入表單 (如果有的話)

顯示表單前,您必須先確認表單是否可用。 這可能是因為使用者無法啟用「廣告追蹤」功能,或已將使用者標記為未滿規定年齡。

如要查看表單的可用性,請使用您先前建立的the isConsentFormAvailable() method on the ConsentInformation instance 。

然後,新增包裝函式方法以載入表單:

Java

...
       consentInformation.requestConsentInfoUpdate(
           this,
           params,
           new ConsentInformation.OnConsentInfoUpdateSuccessListener() {
               @Override
               public void onConsentInfoUpdateSuccess() {
                   // The consent information state was updated.
                   // You are now ready to check if a form is available.
                   if (consentInformation.isConsentFormAvailable()) {
                       loadForm();
                   }
               }
           },
           new ConsentInformation.OnConsentInfoUpdateFailureListener() {
               @Override
               public void onConsentInfoUpdateFailure(FormError formError) {
                   // Handle the error.

               }
            });
    }

    public void loadForm() {

    }
}

Kotlin

Coming soon.

如要載入表單,請使用 the static loadConsentForm() method on the UserMessagingPlatform class。

Java

public void loadForm() {
    // Loads a consent form. Must be called on the main thread.
    UserMessagingPlatform.loadConsentForm(
        this,
        new UserMessagingPlatform.OnConsentFormLoadSuccessListener() {
            @Override
            public void onConsentFormLoadSuccess(ConsentForm consentForm) {
                MainActivity.this.consentForm = consentForm;
            }
        },
        new UserMessagingPlatform.OnConsentFormLoadFailureListener() {
            @Override
            public void onConsentFormLoadFailure(FormError formError) {
                // Handle the error
            }
        }
    );
}

Kotlin

Coming soon.

必要時顯示表單

決定表單的可用性並載入後,請在ConsentForm 執行個體上使用show() 方法來呈現表單。

使用之前的consentInformation 物件檢查consent status 並更新您的loadForm() 方法:

Java

public void loadForm() {
    UserMessagingPlatform.loadConsentForm(
        this,
        new UserMessagingPlatform.OnConsentFormLoadSuccessListener() {
            @Override
            public void onConsentFormLoadSuccess(ConsentForm consentForm) {
                MainActivity.this.consentForm = consentForm;
                if(consentInformation.getConsentStatus() == ConsentInformation.ConsentStatus.REQUIRED) {
                    consentForm.show(
                        MainActivity.this,
                            new ConsentForm.OnConsentFormDismissedListener() {
                                @Override
                                public void onConsentFormDismissed(@Nullable FormError formError) {
                                    // Handle dismissal by reloading form.
                                    loadForm();
                                }
                            });

                }

            }
        },
        new UserMessagingPlatform.OnConsentFormLoadFailureListener() {
            @Override
            public void onConsentFormLoadFailure(FormError formError) {
                /// Handle Error.
            }
        }
   );
}

Kotlin

Coming soon.

如果您需要在使用者選擇或關閉表單之後執行任何動作,請將該邏輯放入表單的完成處理常式或回呼中。

測試

強制套用地理位置

UMP SDK 可讓您測試應用程式的行為,就像使用位於歐洲經濟區或英國的裝置一樣使用 the setDebugGeography method on ConsentDebugSettings.Builder一樣。

您必須在應用程式的偵錯設定中提供測試裝置的雜湊 ID,才能使用偵錯功能。如果您在沒有設定這個值的情況下呼叫requestConsentInfoUpdate() ,您的應用程式會在執行時記錄必要的 ID 雜湊。

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);
consentInformation.requestConsentInfoUpdate(this, params,
    new ConsentInformation.OnConsentInfoUpdateSuccessListener() {
        @Override
        public void onConsentInfoUpdateSuccess() {
            // The consent information state was updated.
            // You are now ready to check if a form is available.
        }
    },
    new ConsentInformation.OnConsentInfoUpdateFailureListener() {
        @Override
        public void onConsentInfoUpdateFailure(FormError formError) {
            // Handle the error.
        }
    });

Kotlin

Coming soon.

使用 DebugGeography時,您可以選擇將地理位置強制設為下列其中一個選項:

偵錯地理位置 說明
DEBUG_GEOGRAPHY_DISABLED 偵錯地理位置已停用。
DEBUG_GEOGRAPHY_EEA 偵錯裝置的顯示位置為歐洲經濟區。
DEBUG_GEOGRAPHY_NOT_EEA 針對偵錯裝置,地理位置並非位於歐洲經濟區。

請注意,偵錯設定僅適用於測試裝置。根據預設,模擬器已在裝置 ID 清單中加入,因為他們已啟用測試功能。

使用 UMP SDK 測試應用程式時,建議您重設 SDK 的狀態,以便模擬使用者初次安裝體驗。SDK 會提供 reset() 方法,

Java

consentInformation.reset();

Kotlin

consentInformation.reset()

如果您決定全面移除 UMP SDK,則也應呼叫 reset()