Persetujuan di Dalam Iframe Lintas Origin: Pola __tcfapiLocator dan __gppLocator
Masalahnya: Persetujuan Berada di Jendela Teratas
CMP berjalan di halaman Anda, di jendela tingkat atas. Sebagian besar iklan Anda tidak. Kreatif display, rich media, renderer header bidding, dan banyak widget pihak ketiga berjalan di dalam iframe, sering kali pada origin berbeda. Kode dalam iframe lintas origin tidak dapat memanggil fungsi di halaman induk secara langsung, sehingga tidak bisa begitu saja memanggil __tcfapi atau __gpp dan membaca pilihan pengunjung.
Kerangka IAB menyelesaikan hal ini dengan konvensi pesan yang kecil dan terdefinisi dengan baik. Jika Anda membangun produk iklan, embed, atau skrip pengukuran yang berjalan dalam frame, atau men-debug ad stack yang melakukannya, ada baiknya mengetahui persis cara kerjanya.
Frame Locator
Di samping API JavaScript, CMP TCF menambahkan iframe kosong yang tidak terlihat bernama __tcfapiLocator ke halaman tingkat atas. CMP GPP melakukan hal yang sama dengan frame bernama __gppLocator. Frame ini tidak membawa konten. Satu-satunya tugasnya adalah dapat ditemukan: skrip apa pun di frame bersarang mana pun dapat menelusuri hierarki jendela ke atas dan memeriksa apakah frame dengan nama tersebut ada di setiap tingkat.
Karena nama frame terlihat lintas origin melalui window.frames, skrip dalam iframe lintas origin yang bersarang dalam dapat menemukan jendela yang menampung CMP tanpa memiliki akses ke hal lain di halaman itu.
Bagaimana Skrip dalam Frame Menemukan CMP
- Mulai dengan jendela saat ini. Jika __tcfapi ada secara lokal, gunakan langsung — skrip tidak berada dalam frame, atau frame tersebut berbagi CMP.
- Jika tidak, telusuri ke atas: periksa apakah jendela saat ini berisi frame bernama __tcfapiLocator; jika tidak, pindah ke window.parent dan periksa lagi, berhenti di jendela teratas.
- Ketika locator ditemukan, jendela yang memuatnya adalah jendela CMP. Komunikasi kini terjadi melalui postMessage.
Bungkus setiap akses dalam try/catch, karena beberapa browser atau pengaturan sandboxing melempar error pada akses properti lintas origin, dan hentikan loop ketika window.parent sama dengan jendela saat ini.
Format Pesan
Untuk TCF, skrip dalam frame mengirim pesan ke jendela CMP berisi objek dengan properti __tcfapiCall. Di dalamnya ada empat kolom:
- command — misalnya getTCData, ping, atau addEventListener;
- parameter — argumen apa pun yang dibutuhkan perintah, atau null;
- version — versi API, 2 untuk TCF v2;
- callId — nilai unik yang dihasilkan pemanggil.
CMP mendengarkan pesan-pesan ini, menjalankan perintah, dan mengirim balik objek dengan properti __tcfapiReturn yang berisi returnValue, success, dan callId yang sama. Pemanggil menyimpan peta callback yang menunggu dengan kunci callId, mendengarkan event message, dan meneruskan setiap respons ke callback yang tepat. GPP mengikuti pola yang sama dengan __gppCall dan __gppReturn.
Banyak integrasi menulis proxy kecil: fungsi lokal bernama __tcfapi di dalam frame yang menerjemahkan panggilan menjadi pesan. Kode yang ditulis untuk jendela teratas kemudian berfungsi tanpa perubahan di dalam frame.
Event Listener Lintas Frame
Panggilan addEventListener yang dikirim melalui postMessage bukanlah permintaan sekali pakai. CMP akan mengirim pesan balasan setiap kali status persetujuan berubah, semuanya dengan callId yang sama. Dispatcher Anda karena itu harus menjaga callback tersebut tetap terdaftar dan bukan menghapusnya setelah respons pertama. Melupakan hal ini adalah bug klasik: skrip dalam frame membaca persetujuan sekali dan tidak pernah menyadari penarikan di kemudian hari.
Pertimbangan Keamanan
- Validasi bentuk pesan. Abaikan pesan apa pun yang tidak mengandung properti yang diharapkan, dan parse payload string secara defensif, karena beberapa implementasi mengirim string JSON, bukan objek.
- Jangan percaya begitu saja. Halaman mana pun dapat mengirim pesan ke frame Anda. Perlakukan respons sebagai sinyal persetujuan yang harus dihormati, bukan data terautentikasi, dan jangan biarkan respons memicu tindakan berhak istimewa.
- Gunakan target origin spesifik bila bisa. Ketika origin CMP diketahui, kirim ke origin tersebut, bukan ke semua origin.
Di Mana Pola Ini Tidak Menjangkau
Beberapa lingkungan iklan mengisolasi kreatif dengan lebih ketat. Kontainer SafeFrame, iframe sandbox tanpa izin yang tepat, dan kreatif yang dirender dalam dokumen terpisah mungkin tidak dapat menelusuri pohon frame atau menerima pesan. Dalam kasus itu, sinyal persetujuan biasanya harus diteruskan secara eksplisit, misalnya sebagai parameter pada permintaan iklan atau nilai yang diberikan ad server kepada kreatif, seperti parameter gdpr dan gdpr_consent yang didukung banyak tag iklan.
Daftar Periksa Debugging
- Di DevTools jendela teratas, pastikan frame locator ada di panel Elements.
- Alihkan konteks konsol ke iframe dan periksa apakah locator dapat dijangkau dari sana.
- Catat event message yang masuk di kedua jendela untuk memastikan panggilan dan balasan mengalir.
- Ubah persetujuan di banner dan verifikasi bahwa listener dalam frame menerima pembaruan.
- Uji dengan CMP yang dimuat terlambat, untuk memastikan kode dalam frame mencoba ulang atau menunggu dan tidak langsung menyerah.
Poin Penting
- Frame lintas origin menjangkau CMP melalui frame __tcfapiLocator dan __gppLocator.
- Panggilan dan balasan memakai postMessage dengan __tcfapiCall/__tcfapiReturn atau padanan GPP-nya, dicocokkan berdasarkan callId.
- Jaga callback listener tetap terdaftar agar perubahan persetujuan berikutnya sampai.
- Validasi setiap pesan dan jangan perlakukan sebagai input tepercaya.
- Di mana frame terisolasi sepenuhnya, teruskan persetujuan secara eksplisit pada permintaan iklan.