หน้านี้ได้รับการแปลโดย Cloud Translation API

เริ่มต้น

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

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

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

ทำตามคู่มือเริ่มต้นใช้งานจนจบ

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

หากคุณกำลังดำเนินการตามข้อกำหนดที่เกี่ยวข้องกับ GDPR โปรดอ่าน ข้อกำหนดของ IAB ส่งผลต่อข้อความขอความยินยอมในสหภาพยุโรปอย่างไร

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

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

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

ติดตั้ง SDK

ทำตามขั้นตอนเพื่อติดตั้ง SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google (GMA) C++ UMP C++ SDK จะรวมอยู่ใน GMA C++ SDK
อย่าลืมกำหนดค่ารหัสแอป AdMob ของแอปในโปรเจ็กต์ก่อนดำเนินการต่อ
ในโค้ด ให้เริ่มต้น 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 ได้แก่

เรียกใช้ OnCompletion() ซึ่งส่งผ่านฟังก์ชัน Callback ของคุณเอง ซึ่งจะเรียกใช้เมื่อการดำเนินการเสร็จสิ้น
ตรวจสอบ 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

คุณควรขออัปเดตข้อมูลความยินยอมของผู้ใช้ทุกครั้งที่เปิดแอปโดยใช้ 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 ที่ที่ควรตรวจสอบขณะรวบรวมความยินยอม ได้แก่

เมื่อรวบรวมความยินยอมในเซสชันปัจจุบันแล้ว
ทันทีที่คุณโทรหา 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;
      }
    }
  }
}

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

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

ทั้งสองสามารถทำได้โดยดำเนินการดังนี้

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

การทดสอบ

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

โทร 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);
}

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

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