Согласие внутри кросс-доменных 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

  1. Начните с текущего окна. Если __tcfapi существует локально, используйте её напрямую — скрипт не во фрейме, или фрейм использует ту же CMP.
  2. Иначе поднимайтесь вверх в цикле: проверьте, содержит ли текущее окно фрейм с именем __tcfapiLocator; если нет, перейдите к window.parent и проверьте снова, остановившись на верхнем окне.
  3. Когда локатор найден, окно, которое его содержит, и есть окно CMP. Дальше общение идёт через postMessage.

Оборачивайте каждое обращение в try/catch, потому что некоторые браузеры или настройки песочницы выбрасывают исключение при кросс-доменном доступе к свойствам, и останавливайте цикл, когда window.parent совпадает с текущим окном.

Формат сообщений

Для TCF скрипт во фрейме отправляет окну CMP сообщение, содержащее объект со свойством __tcfapiCall. Внутри него четыре поля:

CMP слушает эти сообщения, выполняет команду и отправляет обратно объект со свойством __tcfapiReturn, содержащий returnValue, success и тот же callId. Вызывающая сторона хранит таблицу ожидающих callback, ключом которой служит callId, слушает события message и передаёт каждый ответ нужному callback. GPP следует тому же шаблону с __gppCall и __gppReturn.

Многие интеграции пишут небольшой прокси: локальную функцию с именем __tcfapi внутри фрейма, которая превращает вызовы в сообщения. Код, написанный для верхнего окна, тогда работает во фрейме без изменений.

Event listener между фреймами

Вызов addEventListener, отправленный через postMessage, — это не разовый запрос. CMP будет присылать ответное сообщение при каждом изменении состояния согласия, все с тем же callId. Поэтому ваш диспетчер должен оставлять этот callback зарегистрированным, а не удалять его после первого ответа. Забыть об этом — классическая ошибка: скрипт во фрейме читает согласие один раз и не замечает последующего отзыва.

Вопросы безопасности

Где паттерн не работает

Некоторые рекламные среды изолируют креативы строже. Контейнеры SafeFrame, iframe в песочнице без нужных разрешений и креативы, отображаемые в отдельных документах, могут быть не в состоянии обойти дерево фреймов или получать сообщения. В таких случаях сигнал согласия обычно приходится передавать явно, например параметрами рекламного запроса или значениями, которые рекламный сервер передаёт креативу, такими как параметры gdpr и gdpr_consent, которые поддерживают многие рекламные теги.

Чек-лист отладки

Ключевые выводы

← Блог Читать все →