หน้านี้ได้รับการแปลโดย 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++ SDK 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
```

การเรียกไปยัง 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 จากการดำเนินการล่าสุดด้วย

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

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

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

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

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

หลังจากได้รับสถานะความยินยอมเวอร์ชันล่าสุดแล้ว โปรดโทรหา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() เป็นไปได้ว่าได้รับความยินยอมแล้วในเซสชันก่อนหน้า สำหรับแนวทางปฏิบัติแนะนำสำหรับเวลาในการตอบสนอง เราไม่แนะนำให้รอการโทรกลับเสร็จสมบูรณ์ เพื่อที่คุณจะได้เริ่มโหลดโฆษณาโดยเร็วที่สุดหลังจากเปิดตัวแอปแล้ว

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

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

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