SDK สำหรับ User Messaging Platform (UMP) ของ Google เป็นเครื่องมือด้านความเป็นส่วนตัวและการรับส่งข้อความเพื่อช่วยคุณจัดการตัวเลือกความเป็นส่วนตัว ดูข้อมูลเพิ่มเติมได้ที่ เกี่ยวกับความเป็นส่วนตัวและการรับส่งข้อความ
ข้อกำหนดเบื้องต้น
- Android API ระดับ 21 ขึ้นไป (สำหรับ Android)
สร้างประเภทข้อความ
สร้างข้อความสําหรับผู้ใช้ด้วยประเภทข้อความสําหรับผู้ใช้ที่ใช้ได้รายการใดรายการหนึ่งในส่วนความเป็นส่วนตัวและการแสดงข้อความแจ้งผู้ใช้ของบัญชี AdMob UMP SDK จะพยายามแสดงข้อความความเป็นส่วนตัวที่สร้างจากรหัสแอปพลิเคชัน AdMob ที่กําหนดไว้ในโปรเจ็กต์
ดูรายละเอียดเพิ่มเติมได้ที่เกี่ยวกับความเป็นส่วนตัวและการรับส่งข้อความ
ติดตั้ง SDK
ทําตามขั้นตอนเพื่อติดตั้ง SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google (GMA) เวอร์ชัน C++ UMP C++ SDK จะรวมอยู่ใน GMA C++ SDK
ตรวจสอบว่าคุณได้กําหนดค่ารหัสแอป AdMob ของแอปในโปรเจ็กต์แล้วก่อนดําเนินการต่อ
ในโค้ด ให้เริ่มต้น UMP SDK โดยการเรียกใช้
ConsentInfo::GetInstance()
- สำหรับ Android คุณจะต้องส่ง
JNIEnv
และActivity
ที่ NDK ระบุไว้ คุณต้องทำขั้นตอนนี้เพียงครั้งแรกที่โทรหาGetInstance()
- หรือหากใช้ Firebase C++
SDK ในแอปอยู่แล้ว คุณสามารถส่ง
firebase::App
เมื่อเรียก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
- สำหรับ Android คุณจะต้องส่ง
การเรียกใช้ ConsentInfo::GetInstance()
ทั้งหมดในภายหลังจะแสดงผลอินสแตนซ์เดียวกัน
หากใช้ UMP SDK เสร็จแล้ว คุณสามารถปิด SDK ดังกล่าวได้โดยลบอินสแตนซ์ ConsentInfo
ดังนี้
void ShutdownUserMessagingPlatform() {
ump::ConsentInfo* consent_info = ump::ConsentInfo::GetInstance();
delete consent_info;
}
ใช้ Future
เพื่อตรวจสอบการดำเนินการแบบอะซิงโครนัส
firebase::Future
ช่วยให้คุณระบุสถานะการเสร็จสมบูรณ์ของการเรียกใช้เมธอดแบบไม่พร้อมกันได้
ฟังก์ชัน C++ ของ UMP และการเรียกเมธอดทั้งหมดที่ทำงานแบบไม่พร้อมกันจะแสดงผล Future
และยังมีฟังก์ชัน "ผลลัพธ์ล่าสุด" เพื่อดึงข้อมูล Future
จากการดำเนินการล่าสุดด้วย
คุณดูผลลัพธ์จาก Future
ได้ 2 วิธีดังนี้
- เรียก
OnCompletion()
โดยส่งผ่านฟังก์ชัน Callback ของคุณเอง ซึ่งจะเรียกใช้เมื่อการดำเนินการเสร็จสมบูรณ์ - ตรวจสอบ
status()
ของFuture
เป็นระยะๆ เมื่อสถานะเปลี่ยนจากkFutureStatusPending
เป็นkFutureStatusCompleted
แสดงว่าการดำเนินการเสร็จสมบูรณ์แล้ว
หลังจากการดำเนินการแบบไม่พร้อมกันเสร็จสมบูรณ์แล้ว คุณควรตรวจสอบerror()
ของ Future
เพื่อดูรหัสข้อผิดพลาดของการดำเนินการ หากรหัสข้อผิดพลาดคือ 0
(kConsentRequestSuccess
หรือ kConsentFormSuccess
) แสดงว่าการดำเนินการเสร็จสมบูรณ์แล้ว มิเช่นนั้น ให้ตรวจสอบรหัสข้อผิดพลาดและ error_message()
เพื่อดูว่าเกิดข้อผิดพลาดอะไรขึ้น
การเรียกกลับเมื่อดำเนินการเสร็จสมบูรณ์
ต่อไปนี้คือตัวอย่างวิธีใช้ OnCompletion
เพื่อตั้งค่าการเรียกกลับเมื่อเสร็จสิ้น ซึ่งจะเรียกใช้เมื่อการดำเนินการแบบไม่พร้อมกันเสร็จสมบูรณ์
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()
คำขอนี้จะตรวจสอบสิ่งต่อไปนี้
- ต้องได้รับความยินยอมหรือไม่ เช่น ต้องมีการขอความยินยอมเป็นครั้งแรก หรือการตัดสินใจให้ความยินยอมก่อนหน้านี้หมดอายุแล้ว
- ระบุว่าจำเป็นต้องมีจุดแรกเข้าของตัวเลือกความเป็นส่วนตัวหรือไม่ ข้อความเกี่ยวกับความเป็นส่วนตัวบางรายการกำหนดให้แอปอนุญาตให้ผู้ใช้แก้ไขตัวเลือกความเป็นส่วนตัวได้ทุกเมื่อ
โหลดและแสดงแบบฟอร์มประกาศเกี่ยวกับความเป็นส่วนตัว หากจำเป็น
หลังจากได้รับสถานะความยินยอมล่าสุดแล้ว ให้เรียกใช้
LoadAndShowConsentFormIfRequired()
เพื่อโหลดแบบฟอร์มที่จําเป็นในการรวบรวมความยินยอมของผู้ใช้ หลังจากโหลดแล้ว แบบฟอร์มจะแสดงทันที
โค้ดต่อไปนี้แสดงวิธีขอข้อมูลความยินยอมล่าสุดของผู้ใช้ โค้ดจะโหลดและแสดงแบบฟอร์มข้อความเกี่ยวกับความเป็นส่วนตัว หากจำเป็น
#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.
}
});
}
});
}
ดูตัวอย่างการตรวจสอบการเสร็จสิ้นได้ที่ด้านบน โดยใช้การเรียกดูพูลลูปการอัปเดตแทนการเรียกกลับเมื่อเสร็จสิ้น
ทั้งนี้ขึ้นอยู่กับแพลตฟอร์มหากต้องการดําเนินการใดๆ หลังจากที่ผู้ใช้เลือกหรือปิดแบบฟอร์ม ให้ใส่ตรรกะนั้นในโค้ดที่จัดการ Future
ที่แสดงผลโดย LoadAndShowConsentFormIfRequired()
ตัวเลือกความเป็นส่วนตัว
แบบฟอร์มข้อความเกี่ยวกับความเป็นส่วนตัวบางรายการจะแสดงจากจุดแรกเข้าของตัวเลือกความเป็นส่วนตัวที่ผู้เผยแพร่โฆษณาแสดงผล ซึ่งช่วยให้ผู้ใช้จัดการตัวเลือกความเป็นส่วนตัวได้ทุกเมื่อ ดูข้อมูลเพิ่มเติมเกี่ยวกับข้อความที่ผู้ใช้เห็นที่จุดแรกเข้าของตัวเลือกความเป็นส่วนตัวได้ที่ประเภทข้อความสำหรับผู้ใช้ที่ใช้ได้
ส่งคำขอแสดงโฆษณา
ก่อนขอโฆษณาในแอป ให้ตรวจสอบว่าคุณได้รับความยินยอมจากผู้ใช้โดยใช้
ConsentInfo::GetInstance()‑>
CanRequestAds()
หรือไม่ มี 2 ที่ที่ควรตรวจสอบขณะรวบรวมความยินยอม ได้แก่
- หลังจากรวบรวมความยินยอมในเซสชันปัจจุบันแล้ว
- ทันทีที่คุณโทรหา
RequestConsentInfoUpdate()
เป็นไปได้ว่าได้รับความยินยอมในเซสชันก่อนหน้า เราขอแนะนําว่าอย่ารอให้การเรียกกลับเสร็จสมบูรณ์เพื่อเริ่มโหลดโฆษณาโดยเร็วที่สุดหลังจากเปิดแอปตามแนวทางปฏิบัติแนะนำเกี่ยวกับเวลาในการตอบสนอง
หากเกิดข้อผิดพลาดระหว่างกระบวนการรวบรวมความยินยอม คุณควรตรวจสอบว่าสามารถขอโฆษณาได้หรือไม่ UMP SDK จะใช้สถานะความยินยอมจากเซสชันก่อนหน้า
ตัวอย่างที่สมบูรณ์ต่อไปนี้ใช้การสำรวจแบบวนซ้ำสำหรับอัปเดต แต่คุณจะใช้ OnCompletion
Callback เพื่อตรวจสอบการดำเนินการแบบไม่พร้อมกันก็ได้ ใช้เทคนิคใดก็ได้ที่เหมาะกับโครงสร้างโค้ดของคุณมากกว่า
#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;
}
}
}
}
การทดสอบ
หากต้องการทดสอบการผสานรวมในแอปขณะพัฒนา ให้ทำตามขั้นตอนเหล่านี้เพื่อลงทะเบียนอุปกรณ์ทดสอบแบบเป็นโปรแกรม อย่าลืมนำโค้ดที่กำหนดรหัสอุปกรณ์ทดสอบเหล่านี้ออกก่อนที่จะเผยแพร่แอป
- โทรมาที่
RequestConsentInfoUpdate()
ตรวจสอบเอาต์พุตของบันทึกสำหรับข้อความที่คล้ายกับตัวอย่างต่อไปนี้ ซึ่งจะแสดงรหัสอุปกรณ์และวิธีเพิ่มลงในอุปกรณ์ทดสอบ
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]
คัดลอกรหัสอุปกรณ์ทดสอบไปยังคลิปบอร์ด
แก้ไขโค้ดเพื่อตั้งค่า
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); }
บังคับใช้ภูมิศาสตร์
SDK ของ UMP มีวิธีทดสอบลักษณะการทํางานของแอปเสมือนว่าอุปกรณ์อยู่ในภูมิภาคต่างๆ เช่น EEA หรือสหราชอาณาจักร โดยใช้ 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();