Mengapa Skrip Anda Perlu Mendengar, Bukan Mengundi

Mana-mana skrip yang bergantung pada persetujuan — tag iklan, pemuat analitik, pembungkus header bidding — perlu tahu dua perkara: sama ada CMP sudah membuat keputusan, dan apakah keputusan itu. Kesilapan lazim ialah membaca kuki semasa halaman dimuatkan, atau mengundi CMP dengan pemasa sehingga sesuatu muncul. Kedua-dua pendekatan itu rosak dengan cara yang boleh diramal: format kuki bersifat dalaman bagi CMP dan boleh berubah, dan pengundian sama ada berjalan terlalu awal atau membazir masa menunggu.

IAB TCF mentakrifkan antara muka JavaScript piawai untuk tugas ini: fungsi __tcfapi. Tutorial ini menerangkan arahan yang benar-benar anda perlukan, acara yang akan anda terima, dan pepijat yang paling kerap muncul dalam pengeluaran.

Stub dan Baris Gilir

CMP TCF dijangka meletakkan stub kecil pada halaman seawal mungkin, sebelum skrip CMP penuh dimuatkan. Stub mentakrifkan window.__tcfapi dan menggilirkan sebarang panggilan yang dibuat sebelum CMP sedia. Apabila CMP selesai dimuatkan, ia memproses baris gilir dan menjawab setiap panggilan.

Inilah yang menjadikannya selamat bagi skrip lain memanggil __tcfapi serta-merta: selagi stub berada dalam halaman sebelum mereka, panggilan mereka tidak hilang. Jika skrip melontarkan ralat kerana __tcfapi tidak ditakrifkan, stub sama ada tiada atau dimuatkan terlalu lewat — betulkan susunan pemuatan dan jangan tambah percubaan semula.

Arahan yang Penting

ping

__tcfapi('ping', 2, callback) mengembalikan status asas tanpa menunggu keputusan pengguna. Responsnya termasuk cmpLoaded, satu cmpStatus seperti stub, loading, loaded atau error, dan displayStatus berupa visible, hidden atau disabled. Ia juga melaporkan gdprApplies sebaik sahaja diketahui. Gunakannya untuk diagnostik dan untuk memutuskan sama ada TCF relevan langsung bagi pelawat ini.

addEventListener

__tcfapi('addEventListener', 2, callback) ialah arahan yang patut digunakan oleh kebanyakan integrasi. Callback menerima objek tcData dan bendera kejayaan, dan dipanggil semula setiap kali keadaan persetujuan berubah. Sejak TCF v2.2, inilah cara yang disyorkan untuk mendapatkan data persetujuan; arahan getTCData yang lebih lama telah dihentikan.

removeEventListener

Setiap objek tcData membawa listenerId. Hantarkannya kepada __tcfapi('removeEventListener', 2, callback, listenerId) apabila skrip anda tidak lagi memerlukan kemas kini — contohnya, pemuat sekali guna yang sudah membuat keputusannya.

Membaca eventStatus

Medan utama dalam tcData ialah eventStatus. Terdapat tiga nilai:

• tcloaded — CMP menemui keputusan tersimpan yang sah dan tiada sepanduk akan dipaparkan. Anda boleh bertindak ke atas data itu serta-merta.
• cmpuishown — sepanduk sedang dipaparkan. Data mencerminkan keadaan sebelumnya, tetapi pengguna mungkin akan mengubahnya.
• useractioncomplete — pengguna baru sahaja membuat atau mengesahkan pilihan. Bertindaklah ke atas data baharu.

Pemuat tipikal menunggu sama ada tcloaded atau useractioncomplete, kemudian menyemak tujuan dan vendor yang diperlukannya. Ia mengabaikan cmpuishown kecuali mungkin untuk mencatat bahawa sepanduk muncul.

Menyemak Tujuan dan Vendor

Dalam tcData, persetujuan dan kepentingan sah didedahkan sebagai objek yang dikunci mengikut ID:

• tcData.purpose.consents[1] — persetujuan untuk Tujuan 1 (storan peranti).
• tcData.purpose.legitimateInterests[7] — status kepentingan sah untuk Tujuan 7.
• tcData.vendor.consents[ID] dan tcData.vendor.legitimateInterests[ID] — status bagi setiap vendor, menggunakan ID Global Vendor List vendor itu.
• tcData.gdprApplies — sama ada CMP menentukan bahawa GDPR terpakai kepada pelawat ini. Jika false, skrip anda harus mengikut logik bukan-TCF-nya.
• tcData.tcString — rentetan terkod, yang anda serahkan kepada rakan kongsi yang menjangkakannya.

Semak kedua-dua tujuan dan vendor. Persetujuan tujuan tanpa persetujuan vendor, atau sebaliknya, tidak mencukupi bagi kebanyakan vendor untuk memproses data.

Iframe dan Panggilan Merentas Bingkai

Iklan dan widget sering berjalan di dalam iframe yang tidak dapat melihat __tcfapi halaman induk. TCF menyelesaikannya dengan protokol postMessage: CMP menambah bingkai bernama __tcfapiLocator pada halaman teratas, dan kod di dalam iframe boleh mengesannya, menghantar mesej __tcfapiCall dan menerima respons __tcfapiReturn. Kebanyakan SDK iklan sudah berbuat demikian. Jika anda menulis kod iframe sendiri, laksanakan corak yang sama dan jangan baca kuki merentas bingkai.

Pepijat Lazim dan Cara Mengesannya

1. Bertindak ke atas cmpuishown. Skrip yang dimuatkan sebaik sahaja mana-mana callback dicetuskan akan berjalan sebelum pengguna memutuskan. Tapis mengikut eventStatus.
2. Membuang pendengar terlalu awal. Jika anda membuangnya selepas callback pertama, anda akan terlepas useractioncomplete kemudian dan tidak pernah memuatkan.
3. Mengabaikan penarikan balik. Skrip yang berterusan harus terus mendengar dan berhenti atau mengkonfigurasi semula dirinya apabila persetujuan ditarik balik.
4. Mengabaikan gdprApplies. Di luar wilayah TCF, objek tujuan mungkin kosong; menganggapnya sebagai “tiada persetujuan” boleh mematikan hasil yang anda dibenarkan peroleh.
5. Tidak menyemak bendera kejayaan. Apabila success ialah false, catatkannya; ia biasanya menandakan persediaan CMP yang rosak.

Menguji Integrasi Anda

Dalam konsol pelayar, panggil __tcfapi('ping', 2, console.log) untuk mengesahkan CMP wujud, kemudian daftarkan pendengar dengan console.log sebagai callback dan klik melalui sepanduk. Anda sepatutnya melihat cmpuishown diikuti useractioncomplete pada lawatan pertama, dan tcloaded semasa muat semula. Ulangi dengan terima semua, tolak semua dan pilihan tersuai, dan pastikan skrip anda berfungsi dengan betul dalam setiap kes.

Perkara Utama

• Gunakan __tcfapi dan jangan baca kuki CMP atau mengundi.
• Pastikan stub CMP dimuatkan sebelum mana-mana skrip yang memanggil API.
• Gunakan addEventListener dan bertindak hanya pada tcloaded atau useractioncomplete.
• Semak status tujuan dan vendor, dan hormati gdprApplies.
• Gunakan corak postMessage __tcfapiLocator di dalam iframe.