Согласие внутри кросс-доменных 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 зарегистрированными, чтобы приходили последующие изменения согласия.
- Проверяйте каждое сообщение и не считайте его доверенными входными данными.
- Там, где фреймы полностью изолированы, передавайте согласие явно в рекламном запросе.