Защо скриптовете трябва да слушат, а не да проверяват

Всеки скрипт, който зависи от съгласие — рекламен таг, зареждач на аналитика, обвивка за header bidding, — трябва да знае две неща: дали CMP вече има решение и какво е то. Честа грешка е да се чете бисквитка при зареждане на страницата или да се проверява CMP с таймер, докато се появи нещо. И двата подхода се чупят предвидимо: форматът на бисквитката е вътрешен за 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) е командата, която повечето интеграции трябва да използват. 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 съгласието и легитимният интерес са представени като обекти с ключове по ID:

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

Проверявайте и целта, и вендора. Съгласие за цел без съгласие за вендор, или обратното, не е достатъчно повечето вендори да обработват данни.

Iframe и междурамкови извиквания

Рекламите и уиджетите често работят в iframe, които не виждат __tcfapi на родителската страница. TCF решава това с протокол postMessage: CMP добавя рамка с име __tcfapiLocator към горната страница, а кодът вътре в iframe може да я намери, да изпрати съобщение __tcfapiCall и да получи отговор __tcfapiReturn. Повечето рекламни SDK вече го правят. Ако пишете собствен код за iframe, приложете същия модел, вместо да четете бисквитки между рамките.

Чести грешки и как да ги забележите

1. Действие при cmpuishown. Скриптовете, които се зареждат при първото задействане на callback, ще се изпълнят преди потребителят да е решил. Филтрирайте по eventStatus.
2. Твърде ранно премахване на слушателя. Ако го премахнете след първия callback, ще пропуснете по-късния useractioncomplete и никога няма да заредите.
3. Игнориране на оттеглянията. Постоянните скриптове трябва да продължат да слушат и да спрат или да се преконфигурират при оттегляне на съгласие.
4. Игнориране на gdprApplies. Извън регионите на TCF обектите за цели могат да са празни; ако го разглеждате като „няма съгласие“, може да изключите приходи, които имате право да печелите.
5. Непроверяване на флага за успех. Когато success е false, запишете го в лога; обикновено сигнализира за повредена настройка на CMP.

Тестване на интеграцията

В конзолата на браузъра извикайте __tcfapi('ping', 2, console.log), за да потвърдите, че CMP присъства, после регистрирайте слушател с console.log като callback и минете през банера. При първо посещение трябва да видите cmpuishown, последвано от useractioncomplete, а при презареждане — tcloaded. Повторете с приемане на всичко, отказ от всичко и персонализиран избор и се уверете, че скриптът ви се държи правилно във всеки случай.

Основни изводи

• Използвайте __tcfapi вместо четене на бисквитки на CMP или проверка по таймер.
• Уверете се, че заглушката на CMP се зарежда преди всеки скрипт, който извиква API.
• Използвайте addEventListener и действайте само при tcloaded или useractioncomplete.
• Проверявайте статуса и на целта, и на вендора и съобразявайте gdprApplies.
• Използвайте модела __tcfapiLocator с postMessage вътре в iframe.