Сагласност унутар cross-origin iframe-ова: образац __tcfapiLocator и __gppLocator
Проблем: сагласност живи у главном прозору
CMP ради на вашој страници, у прозору највишег нивоа. Велики део вашег оглашавања не ради. Display креативе, rich media, header bidding рендерере и многе виџете трећих страна извршавају се унутар iframe-ова, често на другом origin-у. Код у cross-origin iframe-у не може директно да позове функцију на родитељској страници, па не може једноставно да позове __tcfapi или __gpp и прочита избор посетиоца.
IAB оквири то решавају малом, добро дефинисаном конвенцијом слања порука. Ако градите оглашивачке производе, ембедове или скрипте за мерење које раде у оквирима, или дебагујете ад стекове који то раде, вреди тачно знати како функционише.
Locator оквир
Уз JavaScript API, TCF CMP додаје празан, невидљив iframe под именом __tcfapiLocator на страницу највишег нивоа. GPP CMP чини исто са оквиром под именом __gppLocator. Ови оквири немају садржај. Једини посао им је да буду пронадљиви: свака скрипта у било ком угнежђеном оквиру може да се пење уз хијерархију прозора и на сваком нивоу провери да ли постоји оквир са тим именом.
Пошто су имена оквира видљива преко origin-а кроз window.frames, скрипта у дубоко угнежђеном cross-origin iframe-у може да лоцира прозор који хостује CMP а да нема приступ ичему другом на тој страници.
Како скрипта у оквиру проналази CMP
- Почните од текућег прозора. Ако __tcfapi постоји локално, користите га директно — скрипта није у оквиру или оквир дели CMP.
- У супротном, крећите се навише у петљи: проверите да ли текући прозор садржи оквир под именом __tcfapiLocator; ако не, пређите на window.parent и поново проверите, заустављајући се на највишем прозору.
- Када се locator пронађе, прозор који га садржи је прозор CMP-а. Комуникација се сада одвија преко postMessage.
Сваки приступ умотајте у try/catch, јер неки прегледачи или поставке sandbox-а бацају грешку при cross-origin приступу својствима, и зауставите петљу када window.parent буде једнак текућем прозору.
Формат поруке
За TCF, скрипта у оквиру шаље поруку прозору CMP-а која садржи објекат са својством __tcfapiCall. Унутар њега су четири поља:
- command — на пример getTCData, ping или addEventListener;
- parameter — сваки аргумент који команда захтева, или null;
- version — верзија API-ја, 2 за TCF v2;
- callId — јединствена вредност коју генерише позиваоц.
CMP слуша ове поруке, извршава команду и шаље назад објекат са својством __tcfapiReturn који садржи returnValue, success и исти callId. Позиваоц држи мапу callback-ова на чекању по кључу callId, слуша message догађаје и сваки одговор усмерава на прави callback. GPP следи исти образац са __gppCall и __gppReturn.
Многе интеграције пишу мали proxy: локалну функцију под именом __tcfapi унутар оквира која позиве преводи у поруке. Код писан за главни прозор тада ради непромењен унутар оквира.
Event listener-и преко оквира
Позив addEventListener послат преко postMessage није једнократан захтев. CMP ће послати повратну поруку сваки пут када се стање сагласности промени, све са истим callId. Ваш dispatcher зато мора да задржи тај callback регистрован уместо да га обрише након првог одговора. Заборавити то је класична грешка: скрипта у оквиру једном прочита сагласност и никада не примети каснији опозив.
Безбедносна разматрања
- Проверавајте облик поруке. Игноришите сваку поруку која не садржи очекивано својство и опрезно парсирајте string payload-е, јер неке имплементације шаљу JSON стрингове уместо објеката.
- Не верујте слепо. Свака страница може да шаље поруке вашем оквиру. Одговоре третирајте као сигнале сагласности које треба поштовати, а не као аутентификоване податке, и никада не дозвољавајте да покрећу привилеговане радње.
- Користите специфичне циљне origin-е где можете. Када је origin CMP-а познат, шаљите поруку њему, а не свим origin-има.
Докле овај образац не допире
Нека рекламна окружења строже изолују креативе. SafeFrame контејнери, sandbox-ирани iframe-ови без одговарајућих дозвола и креативи рендеровани у засебним документима можда не могу да прођу кроз стабло оквира нити да примају поруке. У тим случајевима сигнал сагласности обично мора да се проследи експлицитно, на пример као параметри на захтеву за оглас или вредности које ад сервер предаје креативу, као што су параметри gdpr и gdpr_consent које подржавају многи ад тагови.
Контролна листа за дебаговање
- У DevTools-у главног прозора потврдите да locator оквири постоје у панелу Elements.
- Пребаците контекст конзоле на iframe и проверите да ли је locator одатле доступан.
- Логујте долазне message догађаје у оба прозора да потврдите да позиви и одговори теку.
- Промените сагласност у банеру и проверите да listener-и у оквирима добијају ажурирање.
- Тестирајте са касно учитаним CMP-ом, да се уверите да код у оквиру покушава поново или чека, а не одустаје одмах.
Кључни закључци
- Cross-origin оквири долазе до CMP-а преко оквира __tcfapiLocator и __gppLocator.
- Позиви и одговори користе postMessage са __tcfapiCall/__tcfapiReturn или GPP еквивалентима, упарени преко callId.
- Држите callback-ове listener-а регистрованим да би касније промене сагласности стизале.
- Проверите сваку поруку и немојте је третирати као поуздан улаз.
- Где су оквири потпуно изоловани, проследите сагласност експлицитно на захтеву за оглас.