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 (untuk Android)

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 SDK

1. Ikuti langkah-langkah untuk menginstal Google Mobile Ads (GMA) C++ SDK. UMP C++ SDK disertakan dalam GMA C++ SDK.

2. Pastikan Anda mengonfigurasi ID aplikasi AdMob aplikasi Anda dalam project sebelum melanjutkan.

3. Dalam kode Anda, lakukan inisialisasi UMP SDK dengan memanggil ConsentInfo::GetInstance().

   • Di Android, Anda harus meneruskan JNIEnv dan Activity yang disediakan oleh NDK. Anda hanya perlu melakukannya saat pertama kali memanggil GetInstance().
   • Atau, jika sudah menggunakan Firebase C++ SDK di aplikasi, Anda dapat meneruskan firebase::App saat pertama kali memanggil GetInstance().

   #include "firebase/gma/ump.h"
   
   namespace ump = ::firebase::gma::ump;
   
   // Initialize using a firebase::App
   void InitializeUserMessagingPlatform(const firebase::App& app) {
     ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance(app);
   }
   
   // Initialize without a firebase::App
   #ifdef ANDROID
   void InitializeUserMessagingPlatform(JNIEnv* jni_env, jobject activity) {
     ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance(jni_env, activity);
   }
   #else  // non-Android
   void InitializeUserMessagingPlatform() {
     ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();
   }
   #endif
   

Panggilan berikutnya ke ConsentInfo::GetInstance() akan menampilkan instance yang sama.

Catatan: Metode GetInstance() memiliki parameter output firebase::InitResult opsional, yang menampilkan firebase::kInitResultSuccess jika SDK berhasil diinisialisasi, atau firebase::kInitResultFailedMissingDependency jika dependensi yang diperlukan tidak ada di aplikasi Anda. Pastikan Anda telah mengikuti semua langkah penginstalan untuk platform jika error ini terjadi.

Jika sudah selesai menggunakan UMP SDK, Anda dapat menonaktifkan SDK dengan menghapus instance ConsentInfo:

void ShutdownUserMessagingPlatform() {
  ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();
  delete consent_info;
}

Catatan: Anda tidak perlu melakukan inisialisasi Google Mobile Ads C++ SDK sebelum menginisialisasi User Messaging Platform SDK.

Menggunakan Future untuk memantau operasi asinkron

firebase::Future menyediakan cara untuk menentukan status penyelesaian panggilan metode asinkron.

Semua fungsi dan panggilan metode C++ UMP yang beroperasi secara asinkron menampilkan Future, dan juga menyediakan fungsi "hasil terakhir" untuk mengambil Future dari operasi terbaru.

Ada dua cara untuk mendapatkan hasil dari Future:

1. Panggil OnCompletion(), dengan meneruskan fungsi callback Anda sendiri, yang dipanggil saat operasi selesai.
2. Periksa status() Future secara berkala. Saat status berubah dari kFutureStatusPending menjadi kFutureStatusCompleted, operasi telah selesai.

Setelah operasi asinkron selesai, Anda harus memeriksa error() Future untuk mendapatkan kode error operasi. Jika kode error-nya adalah 0 (kConsentRequestSuccess atau kConsentFormSuccess), operasi berhasil diselesaikan; jika tidak, periksa kode error dan error_message() untuk menentukan masalah yang terjadi.

Catatan: Kode error yang ditampilkan oleh RequestConsentInfoUpdate() menggunakan enum ConsentRequestError; semua operasi lainnya menggunakan ConsentFormError.

Callback penyelesaian

Berikut adalah contoh cara menggunakan OnCompletion untuk menetapkan callback penyelesaian, yang dipanggil saat operasi asinkron selesai.

void MyApplicationStart() {
  // [... other app initialization code ...]

  ump::ConsentInfo *consent_info = ump::ConsentInfo::GetInstance();

  // See the section below for more information about RequestConsentInfoUpdate.
  firebase::Future<void> result = consent_info->RequestConsentInfoUpdate(...);

  result.OnCompletion([](const firebase::Future<void>& req_result) {
    if (req_result.error() == ump::kConsentRequestSuccess) {
      // Operation succeeded. You can now call LoadAndShowConsentFormIfRequired().
    } else {
      // Operation failed. Check req_result.error_message() for more information.
    }
  });
}

Memperbarui polling loop

Dalam contoh ini, setelah operasi asinkron dimulai saat peluncuran aplikasi, hasilnya akan diperiksa di tempat lain, dalam fungsi loop update game (yang berjalan satu kali per frame).

ump::ConsentInfo *g_consent_info = nullptr;
bool g_waiting_for_request = false;

void MyApplicationStart() {
  // [... other app initialization code ...]

  g_consent_info = ump::ConsentInfo::GetInstance();
  // See the section below for more information about RequestConsentInfoUpdate.
  g_consent_info->RequestConsentInfoUpdate(...);
  g_waiting_for_request = true;
}

// Elsewhere, in the game's update loop, which runs once per frame:
void MyGameUpdateLoop() {
  // [... other game logic here ...]

  if (g_waiting_for_request) {
    // Check whether RequestConsentInfoUpdate() has finished.
    // Calling "LastResult" returns the Future for the most recent operation.
    firebase::Future<void> result =
      g_consent_info->RequestConsentInfoUpdateLastResult();

    if (result.status() == firebase::kFutureStatusComplete) {
      g_waiting_for_request = false;
      if (result.error() == ump::kConsentRequestSuccess) {
        // Operation succeeded. You can call LoadAndShowConsentFormIfRequired().
      } else {
        // Operation failed. Check result.error_message() for more information.
      }
    }
  }
}

Untuk informasi selengkapnya tentang firebase::Future, lihat dokumentasi Firebase C++ SDK dan dokumentasi GMA C++ SDK.

Catatan: Di UMP C++ SDK, semua operasi asinkron menampilkan firebase::Future<void>.

Mendapatkan informasi izin pengguna

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.

#include "firebase/gma/ump.h"

namespace ump = ::firebase::gma::ump;

void MyApplicationStart(ump::FormParent parent) {
  ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();

  // Create a ConsentRequestParameters struct..
  ump::ConsentRequestParameters params;
  // Set tag for under age of consent. False means users are NOT under age of consent.
  params.tag_for_under_age_of_consent = false;

  consent_info->RequestConsentInfoUpdate(params).OnCompletion(
    [*](const Future<void>& req_result) {
      if (req_result.error() != ump::kConsentRequestSuccess) {
        // req_result.error() is a kConsentRequestError enum.
        LogMessage("Error requesting consent update: %s", req_result.error_message());
      }
      // Consent information is successfully updated.
    });
}

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.

#include "firebase/gma/ump.h"

namespace ump = ::firebase::gma::ump;

void MyApplicationStart(ump::FormParent parent) {
  ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();

  // Create a ConsentRequestParameters struct..
  ump::ConsentRequestParameters params;
  // Set tag for under age of consent. False means users are NOT under age of consent.
  params.tag_for_under_age_of_consent = false;

  consent_info->RequestConsentInfoUpdate(params).OnCompletion(
    [*](const Future<void>& req_result) {
      if (req_result.error() != ump::kConsentRequestSuccess) {
        // req_result.error() is a kConsentRequestError enum.
        LogMessage("Error requesting consent update: %s", req_result.error_message());
      } else {
        consent_info->LoadAndShowConsentFormIfRequired(parent).OnCompletion(
        [*](const Future<void>& form_result) {
          if (form_result.error() != ump::kConsentFormSuccess) {
            // form_result.error() is a kConsentFormError enum.
            LogMessage("Error showing privacy message form: %s", form_result.error_message());
          } else {
            // Either the form was shown and completed by the user, or consent was not required.
          }
        });
      }
    });
}

Lihat di atas untuk mengetahui contoh pemeriksaan penyelesaian menggunakan polling loop update, bukan callback penyelesaian.

Catatan: Bergantung pada platform, FormParent adalah referensi jobject JNI ke Activity Android, atau pointer ke UIViewController iOS, yang ditransmisikan ke jenis FormParent.

Jika Anda perlu melakukan tindakan apa pun setelah pengguna membuat pilihan atau menutup formulir, tempatkan logika tersebut dalam kode yang menangani Future yang ditampilkan oleh LoadAndShowConsentFormIfRequired().

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.

Meminta iklan dengan izin pengguna

Sebelum meminta iklan, gunakan ConsentInfo::GetInstance()‑> CanRequestAds() untuk memeriksa apakah Anda telah mendapatkan izin dari pengguna:

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: ConsentInfo::GetInstance()‑> 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.

Contoh lengkap berikut menggunakan polling loop update, tetapi Anda juga dapat menggunakan callback OnCompletion untuk memantau operasi asinkron. Gunakan teknik mana pun yang lebih sesuai dengan struktur kode Anda.

#include "firebase/future.h"
#include "firebase/gma/gma.h"
#include "firebase/gma/ump.h"

namespace gma = ::firebase::gma;
namespace ump = ::firebase::gma::ump;
using firebase::Future;

ump::ConsentInfo* g_consent_info = nullptr;
// State variable for tracking the UMP consent flow.
enum { kStart, kRequest, kLoadAndShow, kInitGma, kFinished, kErrorState } g_state = kStart;
bool g_ads_allowed = false;

void MyApplicationStart() {
  g_consent_info = ump::ConsentInfo::GetInstance(...);

  // Create a ConsentRequestParameters struct..
  ump::ConsentRequestParameters params;
  // Set tag for under age of consent. False means users are NOT under age of consent.
  params.tag_for_under_age_of_consent = false;

  g_consent_info->RequestConsentInfoUpdate(params);
  // CanRequestAds() can return a cached value from a previous run immediately.
  g_ads_allowed = g_consent_info->CanRequestAds();
  g_state = kRequest;
}

// This function runs once per frame.
void MyGameUpdateLoop() {
  // [... other game logic here ...]

  if (g_state == kRequest) {
    Future<void> req_result = g_consent_info->RequestConsentInfoUpdateLastResult();

    if (req_result.status() == firebase::kFutureStatusComplete) {
      g_ads_allowed = g_consent_info->CanRequestAds();
      if (req_result.error() == ump::kConsentRequestSuccess) {
        // You must provide the FormParent (Android Activity or iOS UIViewController).
        ump::FormParent parent = GetMyFormParent();
        g_consent_info->LoadAndShowConsentFormIfRequired(parent);
        g_state = kLoadAndShow;
      } else {
        LogMessage("Error requesting consent status: %s", req_result.error_message());
        g_state = kErrorState;
      }
    }
  }
  if (g_state == kLoadAndShow) {
    Future<void> form_result = g_consent_info->LoadAndShowConsentFormIfRequiredLastResult();

    if (form_result.status() == firebase::kFutureStatusComplete) {
      g_ads_allowed = g_consent_info->CanRequestAds();
      if (form_result.error() == ump::kConsentRequestSuccess) {
        if (g_ads_allowed) {
          // Initialize GMA. This is another asynchronous operation.
          firebase::gma::Initialize();
          g_state = kInitGma;
        } else {
          g_state = kFinished;
        }
        // Optional: shut down the UMP SDK to save memory.
        delete g_consent_info;
        g_consent_info = nullptr;
      } else {
        LogMessage("Error displaying privacy message form: %s", form_result.error_message());
        g_state = kErrorState;
      }
    }
  }
  if (g_state == kInitGma && g_ads_allowed) {
    Future<gma::AdapterInitializationStatus> gma_future = gma::InitializeLastResult();

    if (gma_future.status() == firebase::kFutureStatusComplete) {
      if (gma_future.error() == gma::kAdErrorCodeNone) {
        g_state = kFinished;
        // TODO: Request an ad.
      } else {
        LogMessage("Error initializing GMA: %s", gma_future.error_message());
        g_state = kErrorState;
      }
    }
  }
}

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.

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:

   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 Anda ke papan klip.

4. Ubah kode Anda untuk menetapkan ConsentRequestParameters.debug_settings.debug_device_ids ke daftar ID perangkat pengujian Anda.

   void MyApplicationStart() {
     ump::ConsentInfo consent_info = ump::ConsentInfo::GetInstance(...);
   
     ump::ConsentRequestParameters params;
     params.tag_for_under_age_of_consent = false;
     params.debug_settings.debug_device_ids = {"TEST-DEVICE-HASHED-ID"};
   
     consent_info->RequestConsentInfoUpdate(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 debug_settings.debug_geography. Perhatikan bahwa setelan debug hanya berfungsi di perangkat pengujian.

void MyApplicationStart() {
  ump::ConsentInfo consent_info = ump::ConsentInfo::GetInstance(...);

  ump::ConsentRequestParameters params;
  params.tag_for_under_age_of_consent = false;
  params.debug_settings.debug_device_ids = {"TEST-DEVICE-HASHED-ID"};
  // Geography appears as EEA for debug devices.
  params.debug_settings.debug_geography = ump::kConsentDebugGeographyEEA

  consent_info->RequestConsentInfoUpdate(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.

  ConsentInfo::GetInstance()->Reset();

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