เริ่มต้น

ภายใต้นโยบายความยินยอมของผู้ใช้ EU ของ Google คุณต้องเปิดเผยข้อมูลบางอย่างต่อผู้ใช้ในเขตเศรษฐกิจยุโรป (EEA) และสหราชอาณาจักร และได้รับความยินยอมในการใช้คุกกี้หรือพื้นที่เก็บข้อมูลอื่นในเครื่องในกรณีที่กฎหมายกำหนด รวมถึงให้ใช้ข้อมูลส่วนตัว (เช่น AdID) ในการแสดงโฆษณา นโยบายนี้เป็นผลมาจากข้อกำหนดด้าน ePrivacy และกฎระเบียบให้ความคุ้มครองข้อมูลส่วนบุคคลของผู้บริโภค (GDPR) ของสหภาพยุโรป

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

สิ่งที่ต้องดำเนินการก่อน

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

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

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

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

ติดตั้ง SDK

  1. ทำตามขั้นตอนเพื่อติดตั้ง SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google (GMA) C++ UMP C++ SDK จะรวมอยู่ใน GMA C++ SDK

  2. อย่าลืมกำหนดค่ารหัสแอป AdMob ของแอปในโปรเจ็กต์ก่อนดำเนินการต่อ

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

    • สำหรับ Android คุณจะต้องส่ง JNIEnv และ Activity ที่ NDK ระบุไว้ คุณต้องดำเนินการนี้ในครั้งแรกที่โทรหา GetInstance() เท่านั้น
    • หรือหากคุณใช้ SDK ของ Firebase C++ ในแอปอยู่แล้ว คุณสามารถส่ง 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
    

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

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

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

ใช้ Future เพื่อตรวจสอบการดำเนินการที่ไม่พร้อมกัน

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

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

มี 2 วิธีในการรับผลลัพธ์จาก Future ได้แก่

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

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

การติดต่อกลับเพื่อเสร็จสิ้น

ต่อไปนี้คือตัวอย่างวิธีใช้ 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

เพิ่มรหัสแอปพลิเคชัน

คุณดูรหัสแอปพลิเคชันได้ใน UI ของ AdMob เพิ่มรหัสลงใน โดยใช้ข้อมูลโค้ดต่อไปนี้

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

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

โปรดดูตัวอย่างด้านบนสำหรับการตรวจสอบความเสร็จสมบูรณ์โดยใช้การสำรวจการอัปเดตแบบวนซ้ำ แทนที่จะเรียกกลับว่าเสร็จสมบูรณ์

โหลดและแสดงแบบฟอร์มความยินยอมหากจำเป็น

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

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 consent 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 ที่ที่ควรตรวจสอบขณะรวบรวมความยินยอม ได้แก่

  1. เมื่อรวบรวมความยินยอมในเซสชันปัจจุบันแล้ว
  2. ทันทีที่คุณโทรหา RequestConsentInfoUpdate() อาจเป็นไปได้ว่าอาจได้รับความยินยอมจากผู้ใช้ในเซสชันก่อน แนวทางปฏิบัติแนะนำเกี่ยวกับเวลาในการตอบสนองคือไม่ควรรอให้ Callback เสร็จสมบูรณ์เพื่อให้คุณเริ่มโหลดโฆษณาโดยเร็วที่สุดหลังจากเปิดตัวแอป

หากเกิดข้อผิดพลาดขึ้นในระหว่างกระบวนการรวบรวมคำยินยอม คุณก็ยังพยายามส่งคำขอโฆษณาได้ 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 consent 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. ใช้องค์ประกอบ UI เช่น ปุ่มในหน้าการตั้งค่าของแอป ที่ทริกเกอร์แบบฟอร์มตัวเลือกความเป็นส่วนตัวได้
  2. เมื่อ LoadAndShowConsentFormIfRequired() เสร็จสมบูรณ์แล้ว ให้ตรวจสอบgetPrivacyOptionsRequirementStatus() เพื่อดูว่าจะแสดงองค์ประกอบ UI ที่แสดงแบบฟอร์มตัวเลือกความเป็นส่วนตัวได้หรือไม่
  3. เมื่อผู้ใช้โต้ตอบกับองค์ประกอบ UI ให้เรียกใช้showPrivacyOptionsForm() เพื่อแสดงแบบฟอร์มเพื่อให้ผู้ใช้อัปเดตตัวเลือกความเป็นส่วนตัวได้ทุกเมื่อ

การทดสอบ

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

  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 หรือสหราชอาณาจักรโดยใช้ ConsentRequestParameters.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();