Чому скриптам варто слухати, а не опитувати

Будь-якому скрипту, що залежить від згоди — рекламному тегу, завантажувачу аналітики, обгортці header bidding, — потрібно знати дві речі: чи є в CMP уже рішення і яке воно. Поширена помилка — читати cookie під час завантаження сторінки або опитувати CMP за таймером, доки щось не з’явиться. Обидва підходи ламаються передбачувано: формат cookie внутрішній для CMP і може змінитися, а опитування або спрацьовує надто рано, або марно витрачає час на очікування.

IAB TCF визначає для цього завдання стандартний JavaScript-інтерфейс — функцію __tcfapi. У цьому посібнику розглянуто команди, які справді потрібні, події, які ви отримуватимете, і помилки, що найчастіше трапляються в продакшені.

Заглушка та черга

CMP на основі TCF має якомога раніше розмістити на сторінці невелику заглушку (stub), ще до завантаження основного скрипта CMP. Заглушка визначає window.__tcfapi і ставить у чергу всі виклики, зроблені до готовності CMP. Коли CMP завершує завантаження, він обробляє чергу й відповідає на кожен виклик.

Саме завдяки цьому інші скрипти можуть безпечно викликати __tcfapi одразу: доки заглушка розташована на сторінці раніше за них, їхні виклики не губляться. Якщо скрипт падає через те, що __tcfapi не визначена, заглушка або відсутня, або завантажується надто пізно — виправляйте порядок завантаження, а не додавайте повторні спроби.

Команди, які мають значення

ping

__tcfapi('ping', 2, callback) повертає базовий статус, не чекаючи рішення користувача. Відповідь містить cmpLoaded, cmpStatus зі значеннями на кшталт stub, loading, loaded чи error, а також displayStatus зі значенням visible, hidden або disabled. Він також повідомляє gdprApplies, коли це стає відомо. Використовуйте його для діагностики й щоб зрозуміти, чи актуальний TCF для цього відвідувача взагалі.

addEventListener

__tcfapi('addEventListener', 2, callback) — команда, яку має використовувати більшість інтеграцій. Колбек отримує об’єкт tcData і прапорець успіху та викликається знову щоразу, коли змінюється стан згоди. Починаючи з TCF v2.2 це рекомендований спосіб отримання даних про згоду; стару команду getTCData визнано застарілою.

removeEventListener

Кожен об’єкт tcData містить listenerId. Передайте його в __tcfapi('removeEventListener', 2, callback, listenerId), коли вашому скрипту більше не потрібні оновлення — наприклад, одноразовому завантажувачу, який уже ухвалив рішення.

Читання eventStatus

Ключове поле в tcData — eventStatus. Воно має три значення:

• tcloaded — CMP знайшов дійсне збережене рішення, і банер не показуватиметься. Можна одразу діяти на основі даних.
• cmpuishown — банер відображається. Дані відображають попередній стан, але користувач ось-ось може його змінити.
• useractioncomplete — користувач щойно зробив або підтвердив вибір. Діяйте за новими даними.

Типовий завантажувач чекає на tcloaded або useractioncomplete, потім перевіряє потрібні йому цілі та вендорів. Подію cmpuishown він ігнорує, хіба що записує в лог, що банер з’явився.

Перевірка цілей і вендорів

Усередині tcData згода та законний інтерес подано об’єктами з ключами-ідентифікаторами:

• tcData.purpose.consents[1] — згода на мету 1 (зберігання на пристрої).
• tcData.purpose.legitimateInterests[7] — статус законного інтересу для мети 7.
• tcData.vendor.consents[ID] і tcData.vendor.legitimateInterests[ID] — статус за кожним вендором із використанням його ідентифікатора в Global Vendor List.
• tcData.gdprApplies — чи визначив CMP, що до цього відвідувача застосовується GDPR. Якщо значення false, скрипту слід виконувати логіку без TCF.
• tcData.tcString — закодований рядок, який ви передаєте партнерам, що його очікують.

Перевіряйте і ціль, і вендора. Згоди на ціль без згоди для вендора (або навпаки) для більшості вендорів недостатньо, щоб обробляти дані.

Iframe і міжфреймові виклики

Реклама та віджети часто працюють усередині iframe, які не бачать __tcfapi батьківської сторінки. TCF розв’язує це протоколом postMessage: CMP додає на верхню сторінку фрейм з іменем __tcfapiLocator, а код усередині iframe може знайти його, надіслати повідомлення __tcfapiCall і отримати відповідь __tcfapiReturn. Більшість рекламних SDK уже це роблять. Якщо ви пишете власний код для iframe, реалізуйте той самий шаблон, а не читайте cookie між фреймами.

Поширені помилки та як їх помітити

1. Дії за cmpuishown. Скрипти, що завантажуються під час будь-якого спрацювання колбека, запустяться до рішення користувача. Фільтруйте за eventStatus.
2. Надто раннє видалення слухача. Якщо видалити його після першого колбека, ви пропустите наступний useractioncomplete і так і не завантажитеся.
3. Ігнорування відкликання згоди. Скрипти, що працюють постійно, мають і далі слухати та зупинятися або переналаштовуватися, коли згоду відкликано.
4. Ігнорування gdprApplies. За межами регіонів TCF об’єкти цілей можуть бути порожніми; вважати це «відсутністю згоди» означає вимкнути дохід, який вам дозволено отримувати.
5. Відсутність перевірки прапорця успіху. Якщо success дорівнює false, запишіть це в лог; зазвичай це сигнал про несправне налаштування CMP.

Тестування інтеграції

У консолі браузера викличте __tcfapi('ping', 2, console.log), щоб переконатися, що CMP на місці, потім зареєструйте слухача з console.log як колбеком і пройдіть по банеру. Під час першого візиту ви маєте побачити cmpuishown, а за ним useractioncomplete, а після перезавантаження — tcloaded. Повторіть для варіантів «прийняти все», «відхилити все» та власного вибору й переконайтеся, що скрипт коректно працює в кожному випадку.

Головні висновки

• Використовуйте __tcfapi замість читання cookie CMP чи опитування.
• Переконайтеся, що заглушка CMP завантажується раніше за будь-який скрипт, який викликає API.
• Використовуйте addEventListener і діяйте лише за tcloaded або useractioncomplete.
• Перевіряйте статус і цілі, і вендора та враховуйте gdprApplies.
• Усередині iframe застосовуйте шаблон postMessage з __tcfapiLocator.