Prečo by mali vaše skripty počúvať, nie pollovať

Každý skript, ktorý závisí od súhlasu — reklamný tag, loader analytiky, wrapper header biddingu — potrebuje vedieť dve veci: či už CMP má rozhodnutie a aké to rozhodnutie je. Častou chybou je čítať cookie pri načítaní stránky alebo pollovať CMP časovačom, kým sa niečo neobjaví. Oba prístupy zlyhávajú predvídateľným spôsobom: formát cookie je interný pre CMP a môže sa zmeniť a polling sa spustí buď príliš skoro, alebo zbytočne čaká.

IAB TCF definuje pre presne túto úlohu štandardné JavaScriptové rozhranie: funkciu __tcfapi. Tento tutoriál prechádza príkazmi, ktoré skutočne potrebujete, udalosťami, ktoré dostanete, a chybami, ktoré sa v produkcii objavujú najčastejšie.

Stub a fronta

Od CMP podľa TCF sa očakáva, že na stránku umiestni malý stub čo najskôr, ešte pred načítaním celého skriptu CMP. Stub definuje window.__tcfapi a zaraďuje do fronty všetky volania uskutočnené pred tým, než je CMP pripravený. Keď sa CMP dokončí načítavanie, spracuje frontu a odpovie na každé volanie.

Vďaka tomu môžu ostatné skripty bezpečne volať __tcfapi okamžite: pokiaľ je stub na stránke pred nimi, ich volania sa nestratia. Ak skript vyhodí chybu, lebo __tcfapi je nedefinované, stub buď chýba, alebo sa načítava príliš neskoro — opravte poradie načítania namiesto pridávania opakovaní.

Príkazy, na ktorých záleží

ping

__tcfapi('ping', 2, callback) vráti základný stav bez čakania na rozhodnutie používateľa. Odpoveď obsahuje cmpLoaded, cmpStatus ako stub, loading, loaded alebo error a displayStatus s hodnotou visible, hidden alebo disabled. Po zistení hlási aj gdprApplies. Použite ho na diagnostiku a na rozhodnutie, či je TCF pre tohto návštevníka vôbec relevantný.

addEventListener

__tcfapi('addEventListener', 2, callback) je príkaz, ktorý by mala používať väčšina integrácií. Callback dostane objekt tcData a príznak úspechu a volá sa znova pri každej zmene stavu súhlasu. Od TCF v2.2 je to odporúčaný spôsob získania údajov o súhlase; starší príkaz getTCData bol označený za zastaraný.

removeEventListener

Každý objekt tcData nesie listenerId. Odovzdajte ho do __tcfapi('removeEventListener', 2, callback, listenerId), keď váš skript už aktualizácie nepotrebuje — napríklad jednorazový loader, ktorý sa už rozhodol.

Čítanie eventStatus

Kľúčovým poľom v tcData je eventStatus. Má tri hodnoty:

• tcloaded — CMP našiel platné uložené rozhodnutie a banner sa nezobrazí. S údajmi môžete konať okamžite.
• cmpuishown — banner sa zobrazuje. Údaje odrážajú prípadný predchádzajúci stav, ale používateľ ho môže práve meniť.
• useractioncomplete — používateľ práve urobil alebo potvrdil voľbu. Konajte podľa nových údajov.

Typický loader čaká na tcloaded alebo useractioncomplete a potom skontroluje účely a dodávateľov, ktorých potrebuje. cmpuishown ignoruje, najviac si zaloguje, že sa banner objavil.

Kontrola účelov a dodávateľov

V tcData sú súhlas a oprávnený záujem sprístupnené ako objekty indexované podľa ID:

• tcData.purpose.consents[1] — súhlas pre účel 1 (ukladanie v zariadení).
• tcData.purpose.legitimateInterests[7] — stav oprávneného záujmu pre účel 7.
• tcData.vendor.consents[ID] a tcData.vendor.legitimateInterests[ID] — stav pre jednotlivých dodávateľov podľa ich ID v Global Vendor List.
• tcData.gdprApplies — či CMP určil, že sa na tohto návštevníka vzťahuje GDPR. Ak je false, váš skript by mal postupovať podľa svojej logiky mimo TCF.
• tcData.tcString — zakódovaný reťazec, ktorý odovzdávate partnerom, ktorí ho očakávajú.

Kontrolujte účel aj dodávateľa. Súhlas s účelom bez súhlasu dodávateľa, alebo naopak, väčšine dodávateľov na spracúvanie údajov nestačí.

Iframy a volania medzi framami

Reklamy a widgety často bežia v iframoch, ktoré nevidia __tcfapi nadradenej stránky. TCF to rieši protokolom postMessage: CMP pridá do hornej stránky frame s názvom __tcfapiLocator a kód v iframe ho môže nájsť, poslať správu __tcfapiCall a dostať odpoveď __tcfapiReturn. Väčšina reklamných SDK to už robí. Ak píšete vlastný kód pre iframe, implementujte rovnaký vzor namiesto čítania cookies medzi framami.

Časté chyby a ako ich odhaliť

1. Konanie podľa cmpuishown. Skripty, ktoré sa načítajú hneď po spustení ktoréhokoľvek callbacku, pobežia skôr, než sa používateľ rozhodne. Filtrujte podľa eventStatus.
2. Príliš skoré odstránenie listenera. Ak ho odstránite po prvom callbacku, premeškáte neskorší useractioncomplete a nikdy sa nenačíta.
3. Ignorovanie odvolaní. Trvalé skripty by mali ďalej počúvať a pri odvolaní súhlasu sa zastaviť alebo prekonfigurovať.
4. Ignorovanie gdprApplies. Mimo regiónov TCF môžu byť objekty účelov prázdne; ak to považujete za “žiadny súhlas”, môžete vypnúť príjmy, ktoré smiete zarábať.
5. Nekontrolovanie príznaku úspechu. Keď je success false, zalogujte to; zvyčajne to signalizuje pokazené nastavenie CMP.

Testovanie integrácie

V konzole prehliadača zavolajte __tcfapi('ping', 2, console.log), aby ste potvrdili prítomnosť CMP, potom zaregistrujte listener s console.log ako callbackom a prekliknite banner. Pri prvej návšteve by ste mali vidieť cmpuishown a po ňom useractioncomplete, pri opätovnom načítaní tcloaded. Zopakujte to s prijatím všetkého, odmietnutím všetkého a vlastným výberom a overte, že sa váš skript správa správne v každom prípade.

Kľúčové poznatky

• Používajte __tcfapi namiesto čítania cookies CMP alebo pollingu.
• Uistite sa, že sa stub CMP načíta pred každým skriptom, ktorý volá API.
• Používajte addEventListener a konajte iba pri tcloaded alebo useractioncomplete.
• Kontrolujte stav účelu aj dodávateľa a rešpektujte gdprApplies.
• V iframoch používajte vzor __tcfapiLocator cez postMessage.