Mulai

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)

Buat jenis pesan

Buat pesan pengguna dengan salah satu Jenis pesan pengguna yang tersedia di bagian Privasi & tab pesan AdMob menggunakan akun layanan. UMP SDK berupaya menampilkan pesan privasi yang dibuat dari AdMob ID Aplikasi tetapkan dalam project Anda.

Untuk 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 aplikasi AdMob untuk aplikasi ID dalam project sebelum melanjutkan.

  3. Di kode Anda, 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 Anda sudah menggunakan Firebase C++ SDK di aplikasi, Anda dapat meneruskan di firebase::App saat pertama kali Anda 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

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

Jika sudah selesai menggunakan UMP SDK, Anda dapat mematikan SDK dengan menghapus Instance ConsentInfo:

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

Menggunakan Future untuk memantau operasi asinkron

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

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

Ada dua cara untuk mendapatkan hasil dari Future:

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

Setelah operasi asinkron selesai, Anda harus memeriksa error() Future untuk mendapatkan error operasi pada kode sumber. Jika kode error adalah 0 (kConsentRequestSuccess atau kConsentFormSuccess), operasi berhasil diselesaikan; jika tidak, periksa kode {i>error <i}dan error_message() untuk menentukan apa yang salah.

Callback penyelesaian

Berikut adalah contoh cara menggunakan OnCompletion untuk menetapkan callback penyelesaian, yang dipanggil ketika 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.
    }
  });
}

Mengupdate loop polling

Dalam contoh ini, setelah operasi asinkron dimulai saat peluncuran aplikasi, hasil diperiksa di tempat lain, dalam fungsi loop update game (yang berjalan sekali 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 mengetahui informasi selengkapnya tentang firebase::Future, lihat Firebase C++ SDK dokumentasi dan dokumentasi GMA C++ SDK.

Menambahkan ID aplikasi

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

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

  • Apakah izin diperlukan atau tidak. Misalnya, izin diperlukan untuk pertama kali, atau keputusan izin sebelumnya sudah tidak berlaku.
  • Apakah titik entri opsi privasi diperlukan atau tidak. Beberapa pesan privasi mewajibkan aplikasi untuk mengizinkan pengguna mengubah opsi privasi mereka kapan saja.
#include "firebase/gma/ump.h"

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

void MyApplicationStart() {
  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>& result) {
      if (result.error() != ump::kConsentRequestSuccess) {
        LogMessage("Error requesting consent update: %s", result.error_message());
      } else {
        // Consent status is now available.
      }
    });
}

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

Memuat dan menampilkan formulir pesan privasi jika diperlukan

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

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

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

Opsi privasi

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

Untuk menerapkan titik entri opsi privasi, selesaikan langkah-langkah berikut:

  1. Periksa getPrivacyOptionsRequirementStatus().
  2. Jika titik entri opsi privasi diperlukan, tambahkan elemen UI yang terlihat dan dapat berinteraksi ke aplikasi Anda.
  3. Picu formulir opsi privasi menggunakan showPrivacyOptionsForm().

Contoh kode berikut menunjukkan langkah-langkah ini:

Permintaan iklan

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

  • Setelah izin dikumpulkan di sesi saat ini.
  • 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.

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

Contoh lengkap berikut menggunakan update loop polling, tetapi Anda juga dapat menggunakan Callback OnCompletion untuk memantau operasi asinkron. Gunakan teknik mana pun yang lebih cocok 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 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.

  1. Panggil RequestConsentInfoUpdate().

  2. Periksa output log untuk pesan yang mirip dengan contoh berikut, yang menunjukkan ID perangkat 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 ditetapkan ConsentRequestParameters.debug_settings.debug_device_ids untuk 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);
}

Paksa geografi

UMP SDK menyediakan cara untuk menguji perilaku aplikasi seolah-olah perangkat yang berlokasi di EEA atau Inggris Raya menggunakan ConsentRequestParameters.debug_settings.debug_geography. Perlu diketahui 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);
}

Dalam menguji aplikasi dengan UMP SDK, sebaiknya reset SDK agar Anda bisa melakukan simulasi pengalaman penginstalan pertama pengguna. SDK menyediakan metode Reset() untuk melakukannya.

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

Contoh di GitHub