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

Свакој скрипти која зависи од сагласности — оглашивачком тагу, учитавачу аналитике, омотачу за header bidding — потребне су две информације: да ли CMP већ има одлуку и каква је та одлука. Честа грешка је читање колачића при учитавању странице или анкетирање CMP-а тајмером док се нешто не појави. Оба приступа се кваре на предвидљиве начине: формат колачића је интерна ствар CMP-а и може да се промени, а анкетирање се или покрене прерано или губи време чекајући.

IAB TCF дефинише стандардни JavaScript интерфејс баш за тај посао: функцију __tcfapi. Овај туторијал води кроз команде које вам заиста требају, догађаје које ћете примати и грешке које се најчешће појављују у продукцији.

Stub и ред чекања

Од TCF CMP-а се очекује да што раније на страницу постави мали stub, пре него што се учита комплетна CMP скрипта. Stub дефинише window.__tcfapi и ставља у ред све позиве упућене пре него што је CMP спреман. Када CMP заврши учитавање, обрађује ред и одговара на сваки позив.

То омогућава другим скриптама да безбедно позову __tcfapi одмах: све док је stub на страници пре њих, њихови позиви се не губе. Ако скрипта баци грешку јер __tcfapi није дефинисан, stub или недостаје или се учитава прекасно — поправите редослед учитавања уместо додавања поновних покушаја.

Команде које су важне

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 stub учита пре сваке скрипте која позива API.
• Користите addEventListener и делујте само на tcloaded или useractioncomplete.
• Проверите и статус сврхе и статус добављача, и поштујте gdprApplies.
• Унутар iframe-ова користите образац __tcfapiLocator са postMessage-ом.