Съгласие във вътрешността на cross-origin iframe: моделът __tcfapiLocator и __gppLocator
Проблемът: съгласието живее в горния прозорец
CMP работи на вашата страница, в прозореца от най-високо ниво. Голяма част от рекламата ви — не. Дисплейните креативи, rich media, рендерите за header bidding и много уиджети на трети страни работят във вътрешността на iframe, често от друг произход. Код в cross-origin iframe не може да извиква директно функция на родителската страница, така че не може просто да извика __tcfapi или __gpp и да прочете избора на посетителя.
Рамките на IAB решават това с малка, добре дефинирана конвенция за съобщения. Ако създавате рекламни продукти, вграждания или скриптове за измерване, които работят в рамки, или дебъгвате рекламни стекове, които го правят, си струва да знаете точно как работи тя.
Рамката локатор
Наред с JavaScript API, CMP по TCF добавя към страницата от най-високо ниво празен, невидим iframe с име __tcfapiLocator. CMP по GPP прави същото с рамка на име __gppLocator. Рамките не носят съдържание. Единствената им задача е да бъдат откриваеми: всеки скрипт във всяка вложена рамка може да се изкачва по йерархията на прозорците и да проверява дали на всяко ниво съществува рамка с това име.
Тъй като имената на рамките са видими между различни произходи чрез window.frames, скрипт в дълбоко вложен cross-origin iframe може да открие прозореца, който хоства CMP, без да има достъп до нищо друго на тази страница.
Как скрипт в рамка намира CMP
- Започнете с текущия прозорец. Ако __tcfapi съществува локално, използвайте я директно — скриптът не е в рамка или рамката споделя CMP.
- В противен случай се изкачвайте в цикъл: проверете дали текущият прозорец съдържа рамка на име __tcfapiLocator; ако не, преминете към window.parent и проверете отново, като спрете на горния прозорец.
- Когато локаторът бъде намерен, прозорецът, който го съдържа, е прозорецът на 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.
Много интеграции пишат малък прокси: локална функция на име __tcfapi във вътрешността на рамката, която превръща извикванията в съобщения. Кодът, написан за горния прозорец, тогава работи в рамката без промяна.
Event listener между рамки
Извикване на addEventListener, изпратено чрез postMessage, не е еднократна заявка. CMP ще изпраща връщащо съобщение всеки път, когато състоянието на съгласие се променя, всички със същия callId. Затова диспечерът ви трябва да държи този callback регистриран, вместо да го изтрива след първия отговор. Забравянето на това е класическа грешка: скриптът в рамката чете съгласието веднъж и никога не забелязва по-късно оттегляне.
Съображения за сигурност
- Проверявайте формата на съобщението. Игнорирайте всяко съобщение, което не съдържа очакваното свойство, и разчитайте низови данни предпазливо, тъй като някои имплементации изпращат JSON низове вместо обекти.
- Не вярвайте сляпо. Всяка страница може да изпраща съобщения до вашата рамка. Третирайте отговорите като сигнали за съгласие, които да зачитате, а не като удостоверени данни, и никога не позволявайте да задействат привилегировани действия.
- Използвайте конкретни целеви произходи, където можете. Когато произходът на CMP е известен, изпращайте до него, а не до всички произходи.
Докъде моделът не стига
Някои рекламни среди изолират креативите по-строго. Контейнерите SafeFrame, iframe в sandbox без правилните разрешения и креативите, изобразявани в отделни документи, може да не могат да обходят дървото на рамките или да получават съобщения. В тези случаи сигналът за съгласие обикновено трябва да се предаде изрично, например като параметри в рекламната заявка или стойности, подадени на креатива от рекламния сървър, като параметрите gdpr и gdpr_consent, които много рекламни тагове поддържат.
Контролен списък за дебъгване
- В DevTools на горния прозорец се уверете, че рамките локатор съществуват в панела Elements.
- Превключете контекста на конзолата към iframe и проверете дали локаторът е достъпен оттам.
- Логвайте входящите събития message и в двата прозореца, за да потвърдите, че извикванията и отговорите текат.
- Променете съгласието в банера и проверете дали listener в рамките получават актуализация.
- Тествайте със закъсняло зареждане на CMP, за да се уверите, че кодът в рамката опитва отново или изчаква, вместо да се предава веднага.
Основни изводи
- Cross-origin рамките достигат CMP чрез рамките __tcfapiLocator и __gppLocator.
- Извикванията и отговорите използват postMessage с __tcfapiCall/__tcfapiReturn или еквивалентите в GPP, съпоставяни по callId.
- Дръжте callback функциите на listener регистрирани, за да пристигат по-късните промени в съгласието.
- Проверявайте всяко съобщение и не го третирайте като доверен вход.
- Където рамките са напълно изолирани, предавайте съгласието изрично в рекламната заявка.