Mengapa Skrip Anda Harus Mendengarkan, Bukan Polling

Setiap skrip yang bergantung pada persetujuan — tag iklan, pemuat analitik, wrapper header bidding — perlu mengetahui dua hal: apakah CMP sudah memiliki keputusan, dan apa keputusan itu. Kesalahan umum adalah membaca cookie saat halaman dimuat, atau melakukan polling ke CMP dengan timer sampai sesuatu muncul. Kedua pendekatan itu rusak dengan cara yang mudah ditebak: format cookie bersifat internal bagi CMP dan bisa berubah, dan polling akan berjalan terlalu dini atau membuang waktu menunggu.

IAB TCF mendefinisikan antarmuka JavaScript standar untuk tugas persis seperti ini: fungsi __tcfapi. Tutorial ini membahas perintah yang benar-benar Anda butuhkan, event yang akan Anda terima, dan bug yang paling sering muncul di produksi.

Stub dan Antrean

CMP TCF diharapkan menempatkan stub kecil di halaman sedini mungkin, sebelum skrip CMP lengkap dimuat. Stub mendefinisikan window.__tcfapi dan mengantrekan setiap panggilan yang dilakukan sebelum CMP siap. Ketika CMP selesai dimuat, ia memproses antrean dan menjawab setiap panggilan.

Inilah yang membuat skrip lain aman memanggil __tcfapi segera: selama stub sudah ada di halaman sebelum mereka, panggilan mereka tidak hilang. Jika sebuah skrip melempar error karena __tcfapi tidak terdefinisi, berarti stub hilang atau dimuat terlalu lambat — perbaiki urutan pemuatan alih-alih menambahkan percobaan ulang.

Perintah yang Penting

ping

__tcfapi('ping', 2, callback) mengembalikan status dasar tanpa menunggu keputusan pengguna. Responsnya mencakup cmpLoaded, sebuah cmpStatus seperti stub, loading, loaded atau error, dan displayStatus berupa visible, hidden atau disabled. Ia juga melaporkan gdprApplies setelah diketahui. Gunakan untuk diagnostik dan untuk menentukan apakah TCF relevan sama sekali bagi pengunjung ini.

addEventListener

__tcfapi('addEventListener', 2, callback) adalah perintah yang sebaiknya dipakai sebagian besar integrasi. Callback menerima objek tcData dan flag keberhasilan, dan dipanggil lagi setiap kali status persetujuan berubah. Sejak TCF v2.2, inilah cara yang direkomendasikan untuk mendapatkan data persetujuan; perintah getTCData yang lebih lama sudah dinyatakan usang.

removeEventListener

Setiap objek tcData membawa sebuah listenerId. Teruskan ke __tcfapi('removeEventListener', 2, callback, listenerId) ketika skrip Anda tidak lagi membutuhkan pembaruan — misalnya, pemuat sekali pakai yang sudah mengambil keputusannya.

Membaca eventStatus

Field kunci di tcData adalah eventStatus. Ada tiga nilai:

• tcloaded — CMP menemukan keputusan tersimpan yang valid dan tidak ada banner yang akan ditampilkan. Anda dapat langsung bertindak berdasarkan datanya.
• cmpuishown — banner sedang ditampilkan. Data mencerminkan status sebelumnya, tetapi pengguna mungkin akan mengubahnya.
• useractioncomplete — pengguna baru saja membuat atau mengonfirmasi pilihan. Bertindaklah berdasarkan data baru.

Pemuat yang umum menunggu tcloaded atau useractioncomplete, lalu memeriksa tujuan dan vendor yang dibutuhkannya. Ia mengabaikan cmpuishown kecuali mungkin untuk mencatat bahwa banner muncul.

Memeriksa Tujuan dan Vendor

Di dalam tcData, persetujuan dan kepentingan sah diekspos sebagai objek yang dikunci berdasarkan ID:

• tcData.purpose.consents[1] — persetujuan untuk Tujuan 1 (penyimpanan perangkat).
• tcData.purpose.legitimateInterests[7] — status kepentingan sah untuk Tujuan 7.
• tcData.vendor.consents[ID] dan tcData.vendor.legitimateInterests[ID] — status per vendor, menggunakan ID Global Vendor List milik vendor.
• tcData.gdprApplies — apakah CMP menentukan bahwa GDPR berlaku bagi pengunjung ini. Jika nilainya false, skrip Anda harus mengikuti logika non-TCF-nya.
• tcData.tcString — string yang disandikan, yang Anda teruskan ke mitra yang mengharapkannya.

Periksa tujuan sekaligus vendor. Persetujuan tujuan tanpa persetujuan vendor, atau sebaliknya, tidak cukup bagi sebagian besar vendor untuk memproses data.

Iframe dan Panggilan Lintas Frame

Iklan dan widget sering berjalan di dalam iframe yang tidak dapat melihat __tcfapi milik halaman induk. TCF mengatasinya dengan protokol postMessage: CMP menambahkan frame bernama __tcfapiLocator ke halaman teratas, dan kode di dalam iframe dapat menemukannya, mengirim pesan __tcfapiCall, lalu menerima respons __tcfapiReturn. Sebagian besar SDK iklan sudah melakukannya. Jika Anda menulis kode iframe sendiri, terapkan pola yang sama alih-alih membaca cookie lintas frame.

Bug Umum dan Cara Mengenalinya

1. Bertindak pada cmpuishown. Skrip yang dimuat begitu callback apa pun terpicu akan berjalan sebelum pengguna memutuskan. Saring berdasarkan eventStatus.
2. Menghapus listener terlalu cepat. Jika Anda menghapusnya setelah callback pertama, Anda akan melewatkan useractioncomplete berikutnya dan tidak pernah memuat.
3. Mengabaikan penarikan persetujuan. Skrip yang persisten harus terus mendengarkan dan berhenti atau mengonfigurasi ulang diri ketika persetujuan ditarik.
4. Mengabaikan gdprApplies. Di luar wilayah TCF, objek tujuan bisa kosong; menganggapnya sebagai “tidak ada persetujuan” dapat mematikan pendapatan yang boleh Anda peroleh.
5. Tidak memeriksa flag keberhasilan. Ketika success bernilai false, catat; biasanya itu menandakan pengaturan CMP yang rusak.

Menguji Integrasi Anda

Di konsol browser, panggil __tcfapi('ping', 2, console.log) untuk memastikan CMP ada, lalu daftarkan listener dengan console.log sebagai callback dan klik melalui banner. Anda seharusnya melihat cmpuishown diikuti useractioncomplete pada kunjungan pertama, dan tcloaded saat dimuat ulang. Ulangi dengan terima semua, tolak semua, dan pilihan kustom, lalu pastikan skrip Anda berperilaku benar di setiap kasus.

Poin Penting

• Gunakan __tcfapi alih-alih membaca cookie CMP atau melakukan polling.
• Pastikan stub CMP dimuat sebelum skrip apa pun yang memanggil API.
• Gunakan addEventListener dan bertindak hanya pada tcloaded atau useractioncomplete.
• Periksa status tujuan sekaligus vendor, dan hormati gdprApplies.
• Gunakan pola postMessage __tcfapiLocator di dalam iframe.