เหตุใดสคริปต์ของคุณควรรับฟัง ไม่ใช่วนตรวจ

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

IAB TCF กำหนดอินเทอร์เฟซ JavaScript มาตรฐานสำหรับงานนี้โดยเฉพาะ คือฟังก์ชัน __tcfapi บทช่วยสอนนี้อธิบายคำสั่งที่คุณต้องใช้จริง เหตุการณ์ที่จะได้รับ และบั๊กที่พบบ่อยที่สุดในระบบจริง

สตับและคิว

CMP ของ TCF ถูกคาดหวังให้วางสตับขนาดเล็กไว้ในหน้าให้เร็วที่สุดเท่าที่ทำได้ ก่อนที่สคริปต์ CMP เต็มรูปแบบจะโหลด สตับกำหนด window.__tcfapi และจัดคิวการเรียกใดๆ ที่เกิดขึ้นก่อน CMP พร้อม เมื่อ CMP โหลดเสร็จ จะประมวลผลคิวและตอบทุกการเรียก

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

คำสั่งที่สำคัญ

ping

__tcfapi('ping', 2, callback) คืนสถานะพื้นฐานโดยไม่รอให้ผู้ใช้ตัดสินใจ การตอบกลับประกอบด้วย cmpLoaded, cmpStatus เช่น stub, loading, loaded หรือ error และ displayStatus ที่เป็น visible, hidden หรือ disabled นอกจากนี้ยังรายงาน gdprApplies เมื่อทราบค่าแล้ว ใช้เพื่อการวินิจฉัยและเพื่อตัดสินใจว่า TCF เกี่ยวข้องกับผู้เข้าชมรายนี้หรือไม่

addEventListener

__tcfapi('addEventListener', 2, callback) คือคำสั่งที่การผสานรวมส่วนใหญ่ควรใช้ callback จะได้รับอ็อบเจกต์ tcData และแฟลกความสำเร็จ และจะถูกเรียกอีกทุกครั้งที่สถานะความยินยอมเปลี่ยน ตั้งแต่ TCF v2.2 นี่เป็นวิธีที่แนะนำในการรับข้อมูลความยินยอม คำสั่ง getTCData แบบเก่าถูกประกาศเลิกใช้งานแล้ว

removeEventListener

อ็อบเจกต์ tcData ทุกตัวมี listenerId ส่งค่านั้นไปที่ __tcfapi('removeEventListener', 2, callback, listenerId) เมื่อสคริปต์ของคุณไม่ต้องการการอัปเดตอีกต่อไป เช่น ตัวโหลดแบบครั้งเดียวที่ตัดสินใจเสร็จแล้ว

การอ่านค่า eventStatus

ฟิลด์หลักใน tcData คือ eventStatus มีสามค่า:

• tcloaded — CMP พบการตัดสินใจที่จัดเก็บไว้และใช้ได้ และจะไม่แสดงแบนเนอร์ คุณดำเนินการกับข้อมูลได้ทันที
• cmpuishown — กำลังแสดงแบนเนอร์ ข้อมูลสะท้อนสถานะก่อนหน้า แต่ผู้ใช้อาจกำลังจะเปลี่ยน
• useractioncomplete — ผู้ใช้เพิ่งเลือกหรือยืนยันตัวเลือก ให้ดำเนินการกับข้อมูลใหม่

ตัวโหลดทั่วไปจะรอ tcloaded หรือ useractioncomplete อย่างใดอย่างหนึ่ง แล้วตรวจสอบวัตถุประสงค์และผู้ขายที่ต้องการ โดยไม่สนใจ cmpuishown ยกเว้นอาจบันทึกว่ามีแบนเนอร์ปรากฏ

การตรวจสอบวัตถุประสงค์และผู้ขาย

ภายใน tcData ความยินยอมและประโยชน์ที่ชอบด้วยกฎหมายถูกเปิดเผยเป็นอ็อบเจกต์ที่ใช้ ID เป็นคีย์:

• tcData.purpose.consents[1] — ความยินยอมสำหรับวัตถุประสงค์ที่ 1 (การจัดเก็บบนอุปกรณ์)
• tcData.purpose.legitimateInterests[7] — สถานะประโยชน์ที่ชอบด้วยกฎหมายสำหรับวัตถุประสงค์ที่ 7
• tcData.vendor.consents[ID] และ tcData.vendor.legitimateInterests[ID] — สถานะรายผู้ขาย โดยใช้ ID ของผู้ขายใน Global Vendor List
• tcData.gdprApplies — CMP ตัดสินว่า GDPR ใช้กับผู้เข้าชมรายนี้หรือไม่ หากเป็น false สคริปต์ของคุณควรทำตามตรรกะที่ไม่ใช่ TCF
• tcData.tcString — string ที่เข้ารหัสแล้ว ซึ่งคุณส่งต่อให้พาร์ตเนอร์ที่ต้องการ

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

iframe และการเรียกข้ามเฟรม

โฆษณาและวิดเจ็ตมักทำงานภายใน iframe ซึ่งมองไม่เห็น __tcfapi ของหน้าแม่ TCF แก้ปัญหานี้ด้วยโปรโตคอล postMessage โดย CMP เพิ่มเฟรมชื่อ __tcfapiLocator ไว้ในหน้าบนสุด และโค้ดภายใน iframe สามารถค้นหาเฟรมนั้น ส่งข้อความ __tcfapiCall และรับการตอบกลับ __tcfapiReturn ได้ SDK โฆษณาส่วนใหญ่ทำเช่นนี้อยู่แล้ว หากคุณเขียนโค้ด iframe เอง ให้ใช้รูปแบบเดียวกันแทนการอ่านคุกกี้ข้ามเฟรม

บั๊กที่พบบ่อยและวิธีสังเกต

1. ทำงานตาม cmpuishown สคริปต์ที่โหลดทันทีที่ callback ใดๆ ทำงานจะรันก่อนที่ผู้ใช้ตัดสินใจ ให้กรองตาม eventStatus
2. ลบตัวรับฟังเร็วเกินไป หากลบหลัง callback แรก คุณจะพลาด useractioncomplete ที่ตามมา และไม่มีวันโหลด
3. เพิกเฉยต่อการถอนความยินยอม สคริปต์ที่ทำงานต่อเนื่องควรรับฟังต่อไป และหยุดหรือกำหนดค่าตนเองใหม่เมื่อมีการถอนความยินยอม
4. เพิกเฉยต่อ gdprApplies นอกภูมิภาคที่ใช้ TCF อ็อบเจกต์วัตถุประสงค์อาจว่างเปล่า การตีความว่า “ไม่มีความยินยอม” อาจปิดรายได้ที่คุณมีสิทธิ์หา
5. ไม่ตรวจแฟลกความสำเร็จ เมื่อ success เป็น false ให้บันทึกไว้ ซึ่งมักบ่งชี้ว่าการตั้งค่า CMP เสีย

การทดสอบการผสานรวมของคุณ

ในคอนโซลของเบราว์เซอร์ ให้เรียก __tcfapi('ping', 2, console.log) เพื่อยืนยันว่ามี CMP จากนั้นลงทะเบียนตัวรับฟังโดยใช้ console.log เป็น callback แล้วคลิกผ่านแบนเนอร์ คุณควรเห็น cmpuishown ตามด้วย useractioncomplete ในการเข้าชมครั้งแรก และ tcloaded เมื่อโหลดซ้ำ ทดสอบซ้ำด้วยการยอมรับทั้งหมด ปฏิเสธทั้งหมด และการเลือกเอง แล้วยืนยันว่าสคริปต์ของคุณทำงานถูกต้องในทุกกรณี

ประเด็นสำคัญ

• ใช้ __tcfapi แทนการอ่านคุกกี้ของ CMP หรือการวนถาม
• ตรวจให้แน่ใจว่าสตับของ CMP โหลดก่อนสคริปต์ใดๆ ที่เรียก API
• ใช้ addEventListener และดำเนินการเฉพาะเมื่อได้ tcloaded หรือ useractioncomplete
• ตรวจสอบสถานะทั้งวัตถุประสงค์และผู้ขาย และเคารพ gdprApplies
• ใช้รูปแบบ postMessage ของ __tcfapiLocator ภายใน iframe