Menyiapkan UMP SDK

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

Membuat jenis pesan

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

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 masa berlaku keputusan izin sebelumnya telah berakhir.
  • Apakah titik entri opsi privasi diperlukan. Beberapa pesan privasi mengharuskan aplikasi mengizinkan pengguna mengubah opsi privasi mereka kapan saja.
/**
 * Requests consent information update on app launch.
 */
export function requestConsent(onComplete?: () => void) {
  requestConsentInfoUpdate({}, (error) => {
    if (error) {
      console.warn('Consent info update error:', error.message);
    } else {
      console.log('Consent info update complete.');
    }

    // Load and show consent form if required.
    loadAndPresentConsentForm(onComplete);
  });
}

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.

/**
 * Loads and presents the privacy message form if required to collect user consent.
 */
export function loadAndPresentConsentForm(onComplete?: () => void) {
  loadAndShowConsentFormIfRequired((formError) => {
    if (formError) {
      console.warn('Consent form error:', formError.message);
    } else {
      console.log('Consent gathering complete.');
    }

    // Execute logic that depends on consent state (for example, initialize the SDK).
    onComplete?.();
  });
}

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 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, konfigurasikan elemen UI Anda agar tidak terlihat dan tidak dapat berinteraksi.

/**
 * Helper to determine if the privacy options entry point is required.
 */
export function isPrivacyOptionsRequired(): boolean {
  return (
    getPrivacyOptionsRequirementStatus() ===
    PrivacyOptionsRequirementStatus.REQUIRED
  );
}

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

Menampilkan formulir opsi privasi

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

/**
 * Renders a privacy options button if required by user consent policy.
 */
export function PrivacyOptionsButton({
  onDismissed,
}: {
  onDismissed?: (error?: FormError) => void;
}) {
  const isRequired =
    getPrivacyOptionsRequirementStatus() ===
    PrivacyOptionsRequirementStatus.REQUIRED;

  if (!isRequired) {
    return null;
  }

  const handleShowPrivacyOptions = () => {
    showPrivacyOptionsForm((error) => {
      if (error) {
        console.error('Failed to show privacy options form:', error.message);
      } else {
        console.log('Privacy options form dismissed.');
      }

      // Execute custom logic after form is dismissed.
      onDismissed?.(error);
    });
  };

  return <Button title="Privacy Settings" onPress={handleShowPrivacyOptions} />;
}

Meminta iklan dengan izin pengguna

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

/**
 * Checks whether user consent allows requesting ads and initializes the SDK.
 */
let isMobileAdsInitialized = false;

export function initializeMobileAdsSdkIfConsentGiven() {
  if (canRequestAds()) {
    if (!isMobileAdsInitialized) {
      isMobileAdsInitialized = true;
      initialize({}, (status) => {
        console.log('Google Mobile Ads SDK initialized:', status);
      });
    }
  }
}

Berikut adalah tempat yang dapat diperiksa untuk mengetahui apakah Anda dapat meminta iklan saat mengumpulkan izin:

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

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 redundan

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

Pengujian

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

  1. Hubungi requestConsentInfoUpdate().

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

    Android

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

    iOS

    <UMP SDK>To enable debug mode for this device,
set: UMPDebugSettings.testDeviceIdentifiers = @[2077ef9a63d2b398840261c8221a0c9b]

  3. Salin ID perangkat pengujian ke papan klip.

  4. Ubah kode Anda untuk memanggil consentDebugSettings.testDeviceIdentifiers dan teruskan daftar ID perangkat pengujian Anda.

    /**
 * Registers a test device for testing consent flows.
 */
export function configureTestDevice() {
  requestConsentInfoUpdate(
    {
      consentDebugSettings: {
        debugGeography: DebugGeography.DISABLED,
        testDeviceIdentifiers: ["TEST_DEVICE_HASHED_ID"],
      },
    },
    (error) => {
      if (!error) {
        console.log('Test device registered.');
      }
    },
  );
}

Memaksakan geografi

UMP SDK menyediakan cara untuk menguji perilaku aplikasi Anda seolah-olah perangkat berada di berbagai wilayah, seperti Wilayah Ekonomi Eropa (EEA), Inggris Raya (UK), dan Swiss menggunakan DebugGeography. Perlu diperhatikan bahwa setelan debug hanya berfungsi di perangkat pengujian.

/**
 * Configures debug settings to force EEA geography on a test device.
 */
export function configureDebugGeography() {
  requestConsentInfoUpdate(
    {
      consentDebugSettings: {
        debugGeography: DebugGeography.EEA,
        testDeviceIdentifiers: ["TEST_DEVICE_HASHED_ID"],
      },
    },
    (error) => {
      if (!error) {
        console.log('Consent debug test configuration loaded.');
      }
    },
  );
}

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

/**
 * Resets consent state for testing purposes.
 */
export function resetConsentState() {
  reset();
}