Memulai

Google User Messaging Platform (UMP) SDK adalah alat privasi dan pesan untuk membantu Anda mengelola pilihan privasi. Untuk informasi selengkapnya, lihat Tentang Privasi & pesan.

Prasyarat

• Android API level 21 atau yang lebih tinggi

Membuat jenis pesan

Buat pesan pengguna dengan salah satu Jenis pesan pengguna yang tersedia di tab Privasi & pesan di akun AdMob Anda. UMP SDK mencoba menampilkan pesan privasi yang dibuat dari ID Aplikasi AdMob yang ditetapkan dalam project Anda.

Untuk mengetahui detail selengkapnya, lihat Tentang privasi dan pesan.

Menginstal dengan Gradle

Tambahkan dependensi untuk Google User Messaging Platform SDK ke file Gradle level aplikasi modul Anda, biasanya app/build.gradle:

dependencies {
  implementation("com.google.android.ump:user-messaging-platform:3.1.0")
}

Setelah membuat perubahan pada build.gradle aplikasi, pastikan untuk menyinkronkan project dengan file Gradle.

Menambahkan ID aplikasi

Anda dapat menemukan ID aplikasi di UI AdMob. Tambahkan ID ke AndroidManifest.xml Anda dengan cuplikan kode berikut:

<manifest>
  <application>
    <meta-data
        android:name="com.google.android.gms.ads.APPLICATION_ID"
        android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"/>
  </application>
</manifest>

Mendapatkan informasi izin pengguna

Untuk mendapatkan informasi izin pengguna, lakukan hal berikut:

Deklarasikan instance ConsentInformation:

Java

private final ConsentInformation consentInformation;

Kotlin

private lateinit val consentInformation: ConsentInformation

Lakukan inisialisasi instance ConsentInformation:

Java

consentInformation = UserMessagingPlatform.getConsentInformation(context);

Kotlin

consentInformation = UserMessagingPlatform.getConsentInformation(context)

Anda harus meminta pembaruan informasi izin pengguna di setiap peluncuran aplikasi, menggunakan requestConsentInfoUpdate(). Permintaan ini memeriksa hal berikut:

• Apakah izin diperlukan. Misalnya, izin diperlukan untuk pertama kalinya, atau masa berlaku keputusan izin sebelumnya telah berakhir.
• Apakah titik entri opsi privasi diperlukan. Beberapa pesan privasi memerlukan aplikasi untuk mengizinkan pengguna mengubah opsi privasi mereka kapan saja.

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

Peringatan: Menggunakan cara lain untuk memeriksa status izin, seperti cache di aplikasi Anda atau string izin yang disimpan sebelumnya, dapat menyebabkan error TCF 3.3 jika izin telah berakhir masa berlakunya.

Memuat dan menampilkan formulir pesan privasi

Setelah Anda menerima status izin terbaru, panggil loadAndShowConsentFormIfRequired() untuk memuat formulir yang diperlukan untuk mengumpulkan izin pengguna. Setelah dimuat, formulir akan langsung ditampilkan.

Poin Penting: Jika tidak ada formulir pesan privasi yang mewajibkan pengumpulan izin pengguna sebelum meminta iklan, callback akan segera dipanggil.

Java

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

Kotlin

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

Opsi privasi

Beberapa formulir pesan privasi ditampilkan dari titik entri opsi privasi yang dirender penayang, sehingga pengguna dapat mengelola opsi privasi mereka kapan saja. Untuk mempelajari lebih lanjut pesan yang dilihat pengguna di titik entri opsi privasi, lihat Jenis pesan pengguna yang tersedia.

Memeriksa apakah titik entri opsi privasi diperlukan

Setelah Anda memanggil requestConsentInfoUpdate(), periksa getPrivacyOptionsRequirementStatus() untuk menentukan apakah titik entri opsi privasi diperlukan untuk aplikasi Anda. Jika titik entri diperlukan, tambahkan elemen UI yang terlihat dan dapat berinteraksi ke aplikasi Anda yang menampilkan formulir opsi privasi. Jika titik entri privasi tidak diperlukan, konfigurasi elemen UI Anda agar tidak terlihat dan dapat berinteraksi.

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

Untuk mengetahui daftar lengkap status persyaratan opsi privasi, lihat ConsentInformation.PrivacyOptionsRequirementStatus.

Menampilkan formulir opsi privasi

Saat pengguna berinteraksi dengan elemen Anda, tampilkan formulir opsi privasi:

Java

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

Kotlin

UserMessagingPlatform.showPrivacyOptionsForm(activity, onConsentFormDismissedListener)
GoogleMobileAdsConsentManager.kt

Meminta iklan dengan izin pengguna

Sebelum meminta iklan, gunakan canRequestAds() untuk memeriksa apakah Anda telah mendapatkan izin dari pengguna:

Java

consentInformation.canRequestAds();

Kotlin

consentInformation.canRequestAds()

Berikut adalah tempat untuk memeriksa apakah Anda dapat meminta iklan saat mengumpulkan izin:

• Setelah UMP SDK mengumpulkan izin dalam sesi saat ini.
• Segera setelah Anda memanggil requestConsentInfoUpdate(). UMP SDK mungkin telah mendapatkan izin di sesi aplikasi sebelumnya.

Penting: canRequestAds() selalu menampilkan false hingga Anda memanggil requestConsentInfoUpdate()

Jika terjadi error selama proses pengumpulan izin, periksa apakah Anda dapat meminta iklan. UMP SDK menggunakan status izin dari sesi aplikasi sebelumnya.

Mencegah pekerjaan permintaan iklan yang berlebihan

Saat Anda memeriksa canRequestAds() setelah mengumpulkan izin dan setelah memanggil requestConsentInfoUpdate(), pastikan logika Anda mencegah permintaan iklan yang berlebihan yang mungkin menyebabkan kedua pemeriksaan menampilkan true. Misalnya, dengan variabel boolean.

Pengujian

Jika Anda ingin menguji integrasi di aplikasi saat sedang mengembangkan, ikuti langkah-langkah berikut untuk mendaftarkan perangkat pengujian secara terprogram. Pastikan untuk menghapus kode yang menetapkan ID perangkat pengujian ini sebelum merilis aplikasi.

Catatan: Mulai versi 2.2.0, emulator tidak perlu ditambahkan ke daftar ID perangkat karena merupakan perangkat pengujian secara default.

1. Hubungi requestConsentInfoUpdate().

2. Periksa output log untuk menemukan pesan yang mirip dengan contoh berikut, yang menampilkan ID perangkat Anda dan cara menambahkannya sebagai perangkat pengujian:

   Use new ConsentDebugSettings.Builder().addTestDeviceHashedId("33BE2250B43518CCDA7DE426D04EE231") to set this as a debug device.
   

3. Salin ID perangkat pengujian Anda ke papan klip.

4. Ubah kode Anda untuk memanggil ConsentDebugSettings.Builder().TestDeviceHashedIds dan teruskan daftar ID perangkat pengujian Anda.

   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,
       // ...
   )
   

Memaksa geografi

UMP SDK menyediakan cara untuk menguji perilaku aplikasi Anda seolah-olah perangkat berada di berbagai wilayah, seperti EEA atau Inggris Raya, menggunakan setDebugGeography(). Perhatikan bahwa setelan debug hanya berfungsi di perangkat pengujian.

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,
    ...
)

Mereset status izin

Saat menguji aplikasi dengan UMP SDK, Anda mungkin perlu mereset status SDK agar dapat menyimulasikan pengalaman penginstalan pertama pengguna. SDK menyediakan metode reset() untuk melakukannya.

Java

consentInformation.reset();

Kotlin

consentInformation.reset()

Perhatian: Metode ini hanya ditujukan untuk tujuan pengujian. Anda tidak boleh memanggil reset() dalam kode produksi.

Contoh di GitHub

Lihat contoh lengkap integrasi UMP SDK yang dibahas di halaman ini di Java BannerExample dan Kotlin BannerExample.