เริ่มใช้งาน

SDK สำหรับ User Messaging Platform (UMP) ของ Google เป็นเครื่องมือด้านความเป็นส่วนตัวและการแสดงข้อความแจ้งผู้ใช้ที่จะช่วยคุณจัดการตัวเลือกความเป็นส่วนตัว ดูข้อมูลเพิ่มเติมได้ที่ เกี่ยวกับความเป็นส่วนตัวและการแสดงข้อความแจ้งผู้ใช้

ข้อกำหนดเบื้องต้น

  • Android API ระดับ 21 ขึ้นไป (สำหรับ Android)

สร้างประเภทข้อความ

สร้างข้อความสำหรับผู้ใช้ด้วยประเภทข้อความสำหรับผู้ใช้ที่มีให้เลือกประเภทใดประเภทหนึ่งในแท็บความเป็นส่วนตัวและการแสดงข้อความแจ้งผู้ใช้ ของบัญชี AdMob UMP SDK จะพยายามแสดงข้อความความเป็นส่วนตัวที่สร้างจากรหัสแอปพลิเคชัน AdMob ที่ตั้งค่าไว้ในโปรเจ็กต์

ดูรายละเอียดเพิ่มเติมได้ที่ เกี่ยวกับความเป็นส่วนตัวและการแสดงข้อความแจ้งผู้ใช้

ติดตั้ง SDK

  1. ทำตามขั้นตอนเพื่อ ติดตั้ง Firebase C++ SDK UMP C++ SDK รวมอยู่ใน Firebase C++ SDK

  2. ตรวจสอบว่าคุณได้กำหนดค่ารหัสแอป AdMob ของแอป ในโปรเจ็กต์ ก่อนที่จะดำเนินการต่อ

  3. เริ่มต้น UMP SDK ในโค้ดโดยเรียกใช้ ConsentInfo::GetInstance()

    • ใน Android คุณต้องส่ง JNIEnv และ Activity ที่ NDK จัดหาให้ คุณต้องทำเช่นนี้เฉพาะครั้งแรกที่เรียกใช้ GetInstance()
    • หรือหากคุณใช้ Firebase C++ SDK ในแอปอยู่แล้ว คุณก็ส่ง firebase::App ได้ในครั้งแรกที่เรียกใช้ GetInstance()
    #include "firebase/ump/ump.h"

namespace ump = ::firebase::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

การเรียกใช้ ConsentInfo::GetInstance() ในครั้งต่อๆ ไปจะแสดงผลอินสแตนซ์เดียวกัน

หากใช้ UMP SDK เสร็จแล้ว คุณสามารถปิด SDK ได้โดยลบอินสแตนซ์ ConsentInfo ดังนี้

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

ใช้ Future เพื่อตรวจสอบการดำเนินการแบบอะซิงโครนัส

A firebase::Future ช่วยให้คุณกำหนดสถานะความสมบูรณ์ของการเรียกใช้เมธอดแบบไม่พร้อมกัน ได้

ฟังก์ชันและการเรียกใช้เมธอด UMP C++ ทั้งหมดที่ทำงานแบบไม่พร้อมกันจะแสดงผล Future และยังมีฟังก์ชัน "ผลลัพธ์ล่าสุด" เพื่อดึงข้อมูล Future จากการดำเนินการล่าสุด

คุณรับผลลัพธ์จาก Future ได้ 2 วิธีดังนี้

  1. เรียกใช้ OnCompletion(), โดยส่งฟังก์ชัน Callback ของคุณเอง ซึ่งจะเรียกใช้เมื่อการดำเนินการ เสร็จสมบูรณ์
  2. ตรวจสอบ status() ของ Future เป็นระยะๆ เมื่อ สถานะ เปลี่ยนจาก kFutureStatusPending เป็น kFutureStatusCompleted แสดงว่า การดำเนินการเสร็จสมบูรณ์แล้ว

หลังจากที่การดำเนินการแบบไม่พร้อมกันเสร็จสมบูรณ์แล้ว คุณควรตรวจสอบ error() ของ Future เพื่อรับรหัสข้อผิดพลาดของการดำเนินการ หากรหัสข้อผิดพลาดเป็น 0 (kConsentRequestSuccess หรือ kConsentFormSuccess) แสดงว่าการดำเนินการเสร็จสมบูรณ์แล้ว ไม่เช่นนั้น ให้ตรวจสอบรหัสข้อผิดพลาดและ error_message() เพื่อดูว่าเกิดข้อผิดพลาดอะไรขึ้น

Callback ความสมบูรณ์

ต่อไปนี้คือตัวอย่างวิธีใช้ OnCompletion เพื่อตั้งค่า Callback ความสมบูรณ์ ซึ่งจะเรียกใช้เมื่อการดำเนินการแบบอะซิงโครนัสเสร็จสมบูรณ์

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

การโพลในลูปการอัปเดต

ในตัวอย่างนี้ หลังจากเริ่มการดำเนินการแบบไม่พร้อมกันเมื่อเปิดแอปแล้ว ระบบจะตรวจสอบผลลัพธ์ในฟังก์ชันวนซ้ำการอัปเดตของเกม (ซึ่งทำงาน 1 ครั้งต่อเฟรม)

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

ดูข้อมูลเพิ่มเติมเกี่ยวกับ firebase::Future ได้ในเอกสารประกอบ Firebase C++ SDK และเอกสารประกอบ GMA C++ SDK

คุณควรร้องขอการอัปเดตข้อมูลความยินยอมของผู้ใช้ทุกครั้งที่เปิดแอป โดยใช้ RequestConsentInfoUpdate() คำขอนี้จะตรวจสอบสิ่งต่อไปนี้

  • ต้องได้รับความยินยอมหรือไม่ เช่น ต้องได้รับความยินยอมเป็นครั้งแรก หรือการตัดสินใจให้ความยินยอมก่อนหน้านี้หมดอายุแล้ว
  • ต้องมีจุดแรกเข้าของตัวเลือกความเป็นส่วนตัวหรือไม่ ข้อความความเป็นส่วนตัวบางข้อกำหนดให้แอปอนุญาตให้ผู้ใช้แก้ไขตัวเลือกความเป็นส่วนตัวได้ทุกเมื่อ
#include "firebase/ump/ump.h"

namespace ump = ::firebase::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.
    });
}

โหลดและแสดงแบบฟอร์มข้อความความเป็นส่วนตัว

หลังจากได้รับสถานะความยินยอมล่าสุดแล้ว ให้เรียกใช้ LoadAndShowConsentFormIfRequired() เพื่อโหลดแบบฟอร์มที่จำเป็นในการ รวบรวมความยินยอมของผู้ใช้ หลังจากโหลดแล้ว แบบฟอร์มจะแสดงขึ้นทันที

#include "firebase/ump/ump.h"

namespace ump = ::firebase::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.
          }
        });
      }
    });
}

ดูตัวอย่างการตรวจสอบความสมบูรณ์โดยใช้ การโพลในลูปการอัปเดตแทน Callback ความสมบูรณ์ได้ที่ด้านบน

FormParent

หากต้องการดำเนินการใดๆ หลังจากที่ผู้ใช้เลือกหรือปิดแบบฟอร์ม ให้วางตรรกะดังกล่าวไว้ในโค้ดที่จัดการ Future ซึ่งแสดงผลโดย LoadAndShowConsentFormIfRequired()

ตัวเลือกความเป็นส่วนตัว

แบบฟอร์มข้อความความเป็นส่วนตัวบางแบบจะแสดงจากจุดแรกเข้าของตัวเลือกความเป็นส่วนตัวที่ผู้เผยแพร่โฆษณาสร้างขึ้น ซึ่งช่วยให้ผู้ใช้จัดการตัวเลือกความเป็นส่วนตัวได้ทุกเมื่อ ดูข้อมูลเพิ่มเติมเกี่ยวกับข้อความที่ผู้ใช้จะเห็นที่จุดแรกเข้าของตัวเลือกความเป็นส่วนตัว ได้ที่ ประเภทข้อความสำหรับผู้ใช้ที่มีให้เลือก

ขอโฆษณาโดยได้รับความยินยอมของผู้ใช้

ก่อนที่จะขอโฆษณา ให้ใช้ ConsentInfo::GetInstance()‑> CanRequestAds() เพื่อตรวจสอบว่าคุณได้รับความยินยอมจากผู้ใช้แล้วหรือไม่

ต่อไปนี้คือตำแหน่งที่คุณสามารถตรวจสอบว่าขอโฆษณาได้หรือไม่ขณะรวบรวมความยินยอม

  • หลังจากที่ UMP SDK รวบรวมความยินยอมในเซสชันปัจจุบัน
  • ทันทีหลังจากที่คุณเรียกใช้ RequestConsentInfoUpdate() UMP SDK อาจได้รับความยินยอมในเซสชันแอปก่อนหน้า

หากเกิดข้อผิดพลาดระหว่างกระบวนการรวบรวมความยินยอม ให้ตรวจสอบว่าคุณขอโฆษณาได้หรือไม่ UMP SDK จะใช้สถานะความยินยอมจากเซสชันแอปก่อนหน้า

ป้องกันไม่ให้มีการขอโฆษณาซ้ำซ้อน

เมื่อตรวจสอบ ConsentInfo::GetInstance()‑> CanRequestAds() หลังจากรวบรวมความยินยอมและหลังจากเรียกใช้ RequestConsentInfoUpdate() แล้ว ให้ตรวจสอบว่าตรรกะของคุณป้องกันไม่ให้มีการขอโฆษณาซ้ำซ้อนซึ่งอาจ ทำให้การตรวจสอบทั้ง 2 รายการแสดงผล true เช่น ใช้ตัวแปรบูลีน

ตัวอย่างที่สมบูรณ์ต่อไปนี้ใช้การโพลในลูปการอัปเดต แต่คุณยังใช้ Callback OnCompletionเพื่อตรวจสอบการดำเนินการแบบไม่พร้อมกันได้ด้วย ให้ใช้เทคนิคที่เหมาะกับโครงสร้างโค้ดของคุณมากกว่า

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

namespace gma = ::firebase::gma;
namespace ump = ::firebase::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;
      }
    }
  }
}

การทดสอบ

หากต้องการทดสอบการผสานรวมในแอปขณะพัฒนา ให้ทำตามขั้นตอนต่อไปนี้เพื่อลงทะเบียนอุปกรณ์ทดสอบโดยใช้โปรแกรม อย่าลืมนำโค้ดที่ตั้งค่ารหัสอุปกรณ์ทดสอบเหล่านี้ออกก่อนที่จะเผยแพร่แอป

  1. เรียกใช้ RequestConsentInfoUpdate()

  2. ตรวจสอบเอาต์พุตบันทึกเพื่อหาข้อความที่คล้ายกับตัวอย่างต่อไปนี้ ซึ่งแสดงรหัสอุปกรณ์และวิธีเพิ่มรหัสเป็นอุปกรณ์ทดสอบ

    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. คัดลอกรหัสอุปกรณ์ทดสอบไปยังคลิปบอร์ด

  4. แก้ไขโค้ดเพื่อตั้งค่า ConsentRequestParameters.debug_settings.debug_device_ids เป็นรายการรหัสอุปกรณ์ทดสอบ

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

บังคับภูมิศาสตร์

UMP SDK มีวิธีทดสอบลักษณะการทำงานของแอปเสมือนว่าอุปกรณ์ อยู่ในภูมิภาคต่างๆ เช่น เขตเศรษฐกิจยุโรป (EEA) และ สหราชอาณาจักร (UK) และสวิตเซอร์แลนด์ โดยใช้ debug_settings.debug_geography โปรดทราบว่าการตั้งค่าการแก้ไขข้อบกพร่องจะทำงานในอุปกรณ์ทดสอบเท่านั้น

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

เมื่อทดสอบแอปด้วย UMP SDK คุณอาจพบว่าการรีเซ็ตสถานะของ SDK มีประโยชน์เพื่อให้คุณจำลองประสบการณ์การติดตั้งครั้งแรกของผู้ใช้ได้ SDK มีเมธอด Reset() สำหรับการดำเนินการนี้

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