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 di 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>

Kumpulkan izin

Untuk mengumpulkan izin, selesaikan langkah-langkah berikut:

1. Permintaan informasi izin pengguna terbaru.
2. Memuat dan menampilkan formulir izin, jika diperlukan.

Meminta informasi izin

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

• Apakah izin diperlukan. Misalnya, izin diperlukan untuk pertama kalinya, atau keputusan izin sebelumnya sudah tidak berlaku.
• Apakah titik entri opsi privasi diperlukan atau tidak. Beberapa pesan privasi mengharuskan aplikasi mengizinkan pengguna untuk mengubah opsi privasi kapan saja.

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 jika diperlukan

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

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

Kode berikut menunjukkan cara meminta informasi izin terbaru pengguna. Jika diperlukan, kode akan dimuat dan menampilkan formulir pesan privasi:

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));
GoogleMobileAdsConsentManager.java

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)
  },
)
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:

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

Menambahkan elemen yang terlihat ke aplikasi

Jika titik entri privasi diperlukan, tambahkan elemen UI yang terlihat dan dapat digunakan ke aplikasi Anda yang menampilkan formulir opsi privasi. Jika titik entri privasi tidak diperlukan, konfigurasikan elemen UI Anda agar tidak terlihat dan tidak dapat berinteraksi.

Java

if (googleMobileAdsConsentManager.isPrivacyOptionsRequired()) {
  // Regenerate the options menu to include a privacy setting.
  invalidateOptionsMenu();
}
MyActivity.java

Kotlin

if (googleMobileAdsConsentManager.isPrivacyOptionsRequired) {
  // Regenerate the options menu to include a privacy setting.
  invalidateOptionsMenu()
}
MainActivity.kt

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

Permintaan iklan

Sebelum meminta iklan di aplikasi, periksa apakah Anda telah mendapatkan izin dari pengguna menggunakan canRequestAds(). Ada dua tempat untuk memeriksa saat mengumpulkan izin:

• Setelah izin dikumpulkan dalam sesi saat ini.
• Segera setelah Anda menelepon requestConsentInfoUpdate(). Mungkin izin telah diperoleh di sesi sebelumnya. Sebagai praktik terbaik latensi, sebaiknya jangan menunggu callback selesai agar Anda dapat mulai memuat iklan sesegera mungkin setelah aplikasi diluncurkan.

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

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

Kode berikut memeriksa apakah Anda dapat meminta iklan selama proses pengumpulan izin:

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()
}

Kode berikut menyiapkan Google Mobile Ads SDK setelah izin pengguna dikumpulkan:

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();
}
MyActivity.java

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()
    }
  }
}
MainActivity.kt

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 meneruskan 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 dimaksudkan untuk digunakan hanya 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 pada Java BannerExample dan Kotlin BannerExample.