Memulai

Berdasarkan Izin Pengguna Uni Eropa Google Kebijakan, Anda harus membuat pengungkapan tertentu kepada pengguna Anda di Wilayah Ekonomi Eropa (EEA) serta dengan Inggris Raya dan mendapatkan izin mereka untuk menggunakan cookie atau penyimpanan lokal lainnya, jika diwajibkan secara hukum, dan menggunakan data pribadi (seperti ID iklan) untuk menayangkan iklan. Kebijakan ini mencerminkan persyaratan dalam ePrivacy Directive Uni Eropa dan Peraturan Perlindungan Data Umum (GDPR).

Untuk mendukung penayang dalam memenuhi kewajibannya berdasarkan kebijakan ini, Google menawarkan User Messaging Platform (UMP) SDK. UMP SDK telah diupdate untuk mendukung standar IAB terbaru. Semua konfigurasi ini sekarang dapat dengan mudah ditangani di bidang Ad Manager privasi & untuk mengirim pesan.

Prasyarat

• Selesaikan panduan Memulai

• Android API level 21 atau yang lebih tinggi

• Jika Anda sedang menangani persyaratan terkait GDPR, baca Pengaruh persyaratan IAB terhadap izin Uni Eropa pesan

Buat jenis pesan

Buat pesan pengguna dengan salah satu jenis pesan pengguna yang tersedia di bagian Privasi & tab pesan Pengelola Iklan menggunakan akun layanan. UMP SDK berupaya menampilkan pesan pengguna yang dibuat dari Ad Manager ID Aplikasi tetapkan dalam project Anda. Jika tidak ada pesan yang dikonfigurasi untuk aplikasi Anda, SDK menghasilkan {i>error<i}.

Untuk detail selengkapnya, lihat Tentang privasi dan pesan.

Menginstal dengan Gradle

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

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

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

Menambahkan ID aplikasi

Anda dapat menemukan ID aplikasi di UI Ad Manager. Tambahkan ID ke AndroidManifest.xml 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>

Meminta informasi izin

Anda harus meminta pembaruan informasi izin pengguna di setiap aplikasi luncurkan, menggunakan requestConsentInfoUpdate(). Ini menentukan apakah pengguna perlu memberikan izin jika mereka belum melakukannya, atau jika izin pengguna sudah tidak berlaku.

Berikut adalah contoh cara memeriksa status dari MainActivity di Metode 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 consent 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 consent form.
        },
        ConsentInformation.OnConsentInfoUpdateFailureListener {
          requestConsentError ->
          // Consent gathering failed.
          Log.w(TAG, "${requestConsentError.errorCode}: ${requestConsentError.message}")
        })
  }
}

Peringatan: Menggunakan cara lain untuk memeriksa status izin, seperti cache di atau string izin yang disimpan sebelumnya, dapat menyebabkan Error TCF 3.3 jika izin sudah tidak berlaku.

Memuat dan menampilkan formulir izin jika diperlukan

Penting: API berikut kompatibel dengan UMP SDK versi 2.1.0 atau yang lebih tinggi.

Setelah Anda menerima status izin terbaru, hubungi loadAndShowConsentFormIfRequired() di ConsentForm untuk memuat formulir izin. Jika status izin diperlukan, SDK akan memuat formulir dan segera menyajikannya dari file activityyang disediakan. callback dipanggil setelah formulir ditutup. Jika izin tidak diperlukan, callback akan segera dipanggil.

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

Jika Anda perlu melakukan tindakan apa pun setelah pengguna membuat pilihan atau menolak formulir, tempatkan logika itu di callback untuk formulir Anda.

Permintaan iklan

Sebelum meminta iklan di aplikasi, periksa apakah Anda telah memperoleh izin dari pengguna menggunakan canRequestAds(). Ada dua tempat yang harus diperiksa saat mengumpulkan persetujuan:

1. Setelah izin dikumpulkan di sesi saat ini.
2. Segera setelah Anda menelepon requestConsentInfoUpdate(). Mungkin izin telah diperoleh di sesi sebelumnya. Sebagai latensi praktik terbaiknya, sebaiknya jangan menunggu callback selesai sehingga Anda bisa mulai memuat iklan sesegera mungkin setelah aplikasi diluncurkan.

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

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

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

Opsi privasi

Beberapa formulir izin mengharuskan pengguna mengubah izinnya kapan saja. Patuhi langkah-langkah berikut untuk menerapkan tombol opsi privasi jika diperlukan.

Untuk melakukan hal ini:

1. Implementasikan elemen UI, seperti tombol di halaman setelan aplikasi Anda, yang dapat memicu formulir opsi privasi.
2. Setelah loadAndShowConsentFormIfRequired() selesai, periksa privacyOptionsRequirementStatus() untuk menentukan apakah akan menampilkan elemen UI yang dapat menyajikan formulir opsi privasi.
3. Saat pengguna berinteraksi dengan elemen UI Anda, panggil showPrivacyOptionsForm() untuk menampilkan formulir agar pengguna dapat memperbarui opsi privasi mereka kapan saja.

Contoh berikut menunjukkan cara menyajikan formulir opsi privasi dari MenuItem.

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

Pengujian

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

Catatan: Mulai versi 2.2.0, emulator tidak perlu ditambahkan ke daftar ID perangkat karena sedang diuji perangkat seluler secara default.

1. Panggil requestConsentInfoUpdate().

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

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

3. Salin ID perangkat pengujian ke papan klip.

4. Ubah kode Anda untuk ditelepon DebugGeography.TestDeviceHashedIds dan teruskan daftar ID perangkat pengujian Anda.

Paksa geografi

UMP SDK menyediakan cara untuk menguji perilaku aplikasi seolah-olah perangkat yang berlokasi di EEA atau Inggris Raya menggunakan the setDebugGeography method which takes a DebugGeography on ConsentDebugSettings.Builder. Perlu diketahui 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

Dalam menguji aplikasi dengan UMP SDK, sebaiknya reset SDK agar Anda bisa melakukan simulasi 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

Contoh integrasi UMP SDK: Java | Kotlin