Згода всередині крос-доменних iframe: патерн __tcfapiLocator і __gppLocator
Проблема: згода живе у верхньому вікні
CMP працює на вашій сторінці, у вікні верхнього рівня. Значна частина вашої реклами — ні. Медійні креативи, rich media, рендерери header bidding і багато сторонніх віджетів працюють усередині iframe, часто на іншому джерелі. Код у крос-доменному iframe не може напряму викликати функцію батьківської сторінки, тому він не може просто викликати __tcfapi чи __gpp і прочитати вибір відвідувача.
Фреймворки IAB розв’язують це невеликою, чітко визначеною домовленістю про обмін повідомленнями. Якщо ви створюєте рекламні продукти, вбудовувані блоки чи скрипти вимірювань, що працюють у фреймах, або налагоджуєте рекламні стеки, які це роблять, варто знати, як саме це влаштовано.
Фрейм-локатор
Поряд із JavaScript API CMP за TCF додає на сторінку верхнього рівня порожній невидимий iframe з назвою __tcfapiLocator. CMP за GPP робить те саме з фреймом із назвою __gppLocator. У цих фреймах немає вмісту. Їхнє єдине завдання — бути знайденими: будь-який скрипт у будь-якому вкладеному фреймі може підійматися ієрархією вікон і перевіряти, чи існує на кожному рівні фрейм із такою назвою.
Оскільки назви фреймів видно між джерелами через window.frames, скрипт у глибоко вкладеному крос-доменному iframe може знайти вікно, у якому розміщено CMP, не отримуючи доступу ні до чого іншого на цій сторінці.
Як скрипт у фреймі знаходить CMP
- Почніть із поточного вікна. Якщо __tcfapi існує локально, використовуйте її напряму — скрипт не у фреймі, або фрейм використовує ту саму CMP.
- Інакше піднімайтеся вгору в циклі: перевірте, чи містить поточне вікно фрейм із назвою __tcfapiLocator; якщо ні, перейдіть до window.parent і перевірте знову, зупинившись на верхньому вікні.
- Коли локатор знайдено, вікно, яке його містить, і є вікном CMP. Далі спілкування йде через postMessage.
Обгортайте кожне звернення в try/catch, бо деякі браузери чи налаштування пісочниці викидають виняток під час крос-доменного доступу до властивостей, і зупиняйте цикл, коли 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 у пісочниці без потрібних дозволів і креативи, що відображаються в окремих документах, можуть бути не в змозі обійти дерево фреймів або отримувати повідомлення. У таких випадках сигнал згоди зазвичай доводиться передавати явно, наприклад параметрами рекламного запиту чи значеннями, які рекламний сервер передає креативу, як-от параметри gdpr і gdpr_consent, що їх підтримують багато рекламних тегів.
Чек-лист налагодження
- У DevTools верхнього вікна переконайтеся, що фрейми-локатори існують у панелі Elements.
- Перемкніть контекст консолі на iframe і перевірте, чи досяжний локатор звідти.
- Логуйте вхідні події message в обох вікнах, щоб переконатися, що виклики та відповіді йдуть.
- Змініть згоду в банері й перевірте, що listener у фреймах отримують оновлення.
- Протестуйте з пізнім завантаженням CMP, щоб переконатися, що код у фреймі повторює спроби або чекає, а не здається одразу.
Ключові висновки
- Крос-доменні фрейми досягають CMP через фрейми __tcfapiLocator і __gppLocator.
- Виклики та відповіді використовують postMessage з __tcfapiCall/__tcfapiReturn або аналогами GPP, що зіставляються за callId.
- Тримайте callback listener зареєстрованими, щоб надходили подальші зміни згоди.
- Перевіряйте кожне повідомлення й не вважайте його довіреними вхідними даними.
- Там, де фрейми повністю ізольовані, передавайте згоду явно в рекламному запиті.