Proč by vaše skripty měly naslouchat, ne se dotazovat

Každý skript, který závisí na souhlasu — reklamní tag, zavaděč analytiky, obal pro header bidding — potřebuje vědět dvě věci: zda už CMP má rozhodnutí a jaké to rozhodnutí je. Častou chybou je číst cookie při načtení stránky nebo se CMP dotazovat časovačem, dokud se něco neobjeví. Oba přístupy selhávají předvídatelnými způsoby: formát cookie je interní věcí CMP a může se změnit a dotazování se buď spustí příliš brzy, nebo ztrácí čas čekáním.

IAB TCF definuje standardní rozhraní JavaScript přesně pro tento úkol: funkci __tcfapi. Tento tutoriál provede příkazy, které skutečně potřebujete, událostmi, které budete přijímat, a chybami, které se v produkci objevují nejčastěji.

Stub a fronta

Od CMP s TCF se očekává, že na stránku co nejdříve umístí malý stub, ještě před načtením celého skriptu CMP. Stub definuje window.__tcfapi a do fronty zařazuje všechna volání provedená dříve, než je CMP připraven. Jakmile CMP dokončí načítání, frontu zpracuje a na každé volání odpoví.

Díky tomu mohou ostatní skripty __tcfapi bezpečně volat okamžitě: dokud je stub na stránce před nimi, jejich volání se neztratí. Pokud skript vyhodí chybu, protože __tcfapi není definováno, stub buď chybí, nebo se načítá příliš pozdě — opravte pořadí načítání místo přidávání opakovaných pokusů.

Příkazy, na kterých záleží

ping

__tcfapi('ping', 2, callback) vrací základní stav, aniž by čekal na rozhodnutí uživatele. Odpověď obsahuje cmpLoaded, cmpStatus, například stub, loading, loaded nebo error, a displayStatus s hodnotou visible, hidden nebo disabled. Jakmile je známo, hlásí také gdprApplies. Použijte ho pro diagnostiku a k rozhodnutí, zda je TCF pro tohoto návštěvníka vůbec relevantní.

addEventListener

__tcfapi('addEventListener', 2, callback) je příkaz, který by měla používat většina integrací. Callback obdrží objekt tcData a příznak úspěchu a volá se znovu při každé změně stavu souhlasu. Od TCF v2.2 jde o doporučený způsob získávání dat o souhlasu; starší příkaz getTCData byl označen jako zastaralý.

removeEventListener

Každý objekt tcData nese listenerId. Předejte jej do __tcfapi('removeEventListener', 2, callback, listenerId), když váš skript další aktualizace nepotřebuje — například jednorázový zavaděč, který už své rozhodnutí učinil.

Čtení eventStatus

Klíčovým polem v tcData je eventStatus. Má tři hodnoty:

• tcloaded — CMP našel platné uložené rozhodnutí a banner se nezobrazí. S daty můžete jednat okamžitě.
• cmpuishown — banner se zobrazuje. Data odrážejí předchozí stav, ale uživatel jej možná právě změní.
• useractioncomplete — uživatel právě provedl nebo potvrdil volbu. Jednejte podle nových dat.

Typický zavaděč počká buď na tcloaded, nebo na useractioncomplete, a poté zkontroluje účely a dodavatele, které potřebuje. cmpuishown ignoruje, snad kromě zaznamenání, že se banner objevil.

Kontrola účelů a dodavatelů

Uvnitř tcData jsou souhlas a oprávněný zájem zpřístupněny jako objekty s klíči podle ID:

• tcData.purpose.consents[1] — souhlas s účelem 1 (ukládání v zařízení).
• tcData.purpose.legitimateInterests[7] — stav oprávněného zájmu pro účel 7.
• tcData.vendor.consents[ID] a tcData.vendor.legitimateInterests[ID] — stav pro jednotlivé dodavatele podle ID dodavatele z Global Vendor List.
• tcData.gdprApplies — zda CMP určil, že se na tohoto návštěvníka vztahuje GDPR. Pokud je false, váš skript by se měl řídit svou logikou bez TCF.
• tcData.tcString — kódovaný řetězec, který předáváte partnerům, kteří ho očekávají.

Zkontrolujte účel i dodavatele. Souhlas s účelem bez souhlasu pro dodavatele, nebo naopak, většině dodavatelů ke zpracování dat nestačí.

Iframy a volání mezi rámci

Reklamy a widgety často běží uvnitř iframů, které nevidí __tcfapi nadřazené stránky. TCF to řeší protokolem postMessage: CMP přidá na nejvyšší stránku rámec s názvem __tcfapiLocator, kód uvnitř iframu jej může najít, odeslat zprávu __tcfapiCall a přijmout odpověď __tcfapiReturn. Většina reklamních SDK to již dělá. Pokud píšete vlastní kód iframu, implementujte stejný vzor místo čtení cookies napříč rámci.

Časté chyby a jak je poznat

1. Jednání na cmpuishown. Skripty, které se načtou, jakmile se spustí jakýkoli callback, poběží dříve, než se uživatel rozhodne. Filtrujte podle eventStatus.
2. Příliš brzké odebrání posluchače. Pokud jej odeberete po prvním callbacku, minete pozdější useractioncomplete a skript se nikdy nenačte.
3. Ignorování odvolání. Trvalé skripty by měly dál naslouchat a zastavit se nebo se překonfigurovat, když je souhlas odvolán.
4. Ignorování gdprApplies. Mimo regiony TCF mohou být objekty účelů prázdné; chápání toho jako “žádný souhlas” může vypnout příjmy, které smíte získávat.
5. Nekontrolování příznaku úspěchu. Když je success false, zaznamenejte to; obvykle to signalizuje rozbité nastavení CMP.

Testování integrace

V konzoli prohlížeče zavolejte __tcfapi('ping', 2, console.log), abyste potvrdili přítomnost CMP, poté zaregistrujte posluchače s console.log jako callbackem a proklikejte se bannerem. Při první návštěvě byste měli vidět cmpuishown a po něm useractioncomplete, při opětovném načtení tcloaded. Opakujte s přijetím všeho, odmítnutím všeho a vlastním výběrem a ověřte, že se váš skript v každém případě chová správně.

Hlavní poznatky

• Používejte __tcfapi místo čtení cookies CMP nebo dotazování.
• Zajistěte, aby se stub CMP načetl před každým skriptem, který volá API.
• Používejte addEventListener a jednejte pouze na tcloaded nebo useractioncomplete.
• Kontrolujte stav účelu i dodavatele a respektujte gdprApplies.
• Uvnitř iframů používejte vzor __tcfapiLocator s postMessage.