Persetujuan dalam Iframe Silang Origin: Corak __tcfapiLocator dan __gppLocator
Masalahnya: Persetujuan Berada dalam Tetingkap Teratas
CMP berjalan pada halaman anda, dalam tetingkap peringkat atas. Kebanyakan iklan anda tidak. Kreatif paparan, rich media, renderer header bidding dan banyak widget pihak ketiga berjalan di dalam iframe, selalunya pada origin berbeza. Kod dalam iframe silang origin tidak boleh memanggil fungsi pada halaman induk secara langsung, jadi ia tidak boleh sekadar memanggil __tcfapi atau __gpp dan membaca pilihan pelawat.
Rangka kerja IAB menyelesaikannya dengan konvensyen pemesejan yang kecil dan tertakrif dengan baik. Jika anda membina produk iklan, embed atau skrip pengukuran yang berjalan dalam frame, atau menyahpepijat ad stack yang berbuat demikian, elok anda tahu bagaimana ia berfungsi dengan tepat.
Frame Locator
Di samping API JavaScript, CMP TCF menambah iframe kosong yang tidak kelihatan bernama __tcfapiLocator pada halaman peringkat atas. CMP GPP melakukan perkara sama dengan frame bernama __gppLocator. Frame ini tidak membawa kandungan. Satu-satunya tugasnya ialah boleh ditemui: mana-mana skrip dalam mana-mana frame bersarang boleh menyusuri hierarki tetingkap ke atas dan menyemak sama ada frame dengan nama itu wujud pada setiap peringkat.
Oleh sebab nama frame kelihatan merentas origin melalui window.frames, skrip dalam iframe silang origin yang bersarang dalam boleh mencari tetingkap yang menempatkan CMP tanpa mempunyai akses kepada apa-apa lagi pada halaman itu.
Bagaimana Skrip dalam Frame Menemui CMP
- Mulakan dengan tetingkap semasa. Jika __tcfapi wujud secara setempat, gunakannya terus — skrip tidak berada dalam frame, atau frame itu berkongsi CMP.
- Jika tidak, ulang ke atas: semak sama ada tetingkap semasa mengandungi frame bernama __tcfapiLocator; jika tidak, beralih ke window.parent dan semak lagi, berhenti pada tetingkap teratas.
- Apabila locator ditemui, tetingkap yang mengandunginya ialah tetingkap CMP. Komunikasi kini berlaku melalui postMessage.
Bungkus setiap akses dalam try/catch, kerana sesetengah pelayar atau tetapan sandboxing melontarkan ralat pada akses sifat silang origin, dan hentikan gelung apabila window.parent sama dengan tetingkap semasa.
Format Mesej
Bagi TCF, skrip dalam frame menghantar mesej kepada tetingkap CMP yang mengandungi objek dengan sifat __tcfapiCall. Di dalamnya ada empat medan:
- command — contohnya getTCData, ping atau addEventListener;
- parameter — sebarang argumen yang diperlukan arahan, atau null;
- version — versi API, 2 untuk TCF v2;
- callId — nilai unik yang dijana oleh pemanggil.
CMP mendengar mesej ini, menjalankan arahan dan menghantar balik objek dengan sifat __tcfapiReturn yang mengandungi returnValue, success dan callId yang sama. Pemanggil menyimpan peta callback tertunda berkunci callId, mendengar peristiwa message dan menghantar setiap pulangan kepada callback yang betul. GPP mengikut corak sama dengan __gppCall dan __gppReturn.
Banyak integrasi menulis proksi kecil: fungsi setempat bernama __tcfapi di dalam frame yang menterjemahkan panggilan kepada mesej. Kod yang ditulis untuk tetingkap teratas kemudian berfungsi tanpa perubahan di dalam frame.
Event Listener Merentas Frame
Panggilan addEventListener yang dihantar melalui postMessage bukan permintaan sekali sahaja. CMP akan menghantar mesej pulangan setiap kali keadaan persetujuan berubah, semuanya dengan callId yang sama. Dispatcher anda oleh itu mesti mengekalkan callback itu didaftarkan dan bukannya memadamnya selepas respons pertama. Terlupa perkara ini ialah pepijat klasik: skrip dalam frame membaca persetujuan sekali dan tidak pernah menyedari penarikan balik kemudian.
Pertimbangan Keselamatan
- Sahkan bentuk mesej. Abaikan sebarang mesej yang tidak mengandungi sifat yang dijangka, dan huraikan muatan rentetan secara defensif, kerana sesetengah pelaksanaan menghantar rentetan JSON dan bukannya objek.
- Jangan percaya membuta tuli. Mana-mana halaman boleh menghantar mesej kepada frame anda. Layan respons sebagai isyarat persetujuan yang perlu dihormati, bukan data yang disahkan, dan jangan sekali-kali biarkan ia mencetuskan tindakan berkeistimewaan.
- Gunakan origin sasaran yang spesifik jika boleh. Apabila origin CMP diketahui, hantar kepadanya dan bukan kepada semua origin.
Di Mana Corak Ini Tidak Sampai
Sesetengah persekitaran iklan mengasingkan kreatif dengan lebih ketat. Bekas SafeFrame, iframe sandbox tanpa kebenaran yang betul dan kreatif yang dirender dalam dokumen berasingan mungkin tidak dapat menyusuri pepohon frame atau menerima mesej. Dalam kes itu, isyarat persetujuan lazimnya mesti dihantar secara eksplisit, contohnya sebagai parameter pada permintaan iklan atau nilai yang diberikan ad server kepada kreatif, seperti parameter gdpr dan gdpr_consent yang disokong banyak tag iklan.
Senarai Semak Penyahpepijatan
- Dalam DevTools tetingkap teratas, sahkan frame locator wujud dalam panel Elements.
- Tukar konteks konsol kepada iframe dan semak sama ada locator boleh dicapai dari situ.
- Log peristiwa message yang masuk dalam kedua-dua tetingkap untuk mengesahkan panggilan dan pulangan mengalir.
- Ubah persetujuan dalam sepanduk dan sahkan listener dalam frame menerima kemas kini.
- Uji dengan CMP yang dimuatkan lewat, untuk memastikan kod dalam frame mencuba semula atau menunggu dan bukannya terus menyerah.
Perkara Utama
- Frame silang origin mencapai CMP melalui frame __tcfapiLocator dan __gppLocator.
- Panggilan dan pulangan menggunakan postMessage dengan __tcfapiCall/__tcfapiReturn atau setara GPP, dipadankan melalui callId.
- Pastikan callback listener kekal didaftarkan supaya perubahan persetujuan kemudian sampai.
- Sahkan setiap mesej dan jangan layan sebagai input yang dipercayai.
- Di mana frame terpencil sepenuhnya, hantar persetujuan secara eksplisit pada permintaan iklan.