Miért kell a scripteknek figyelniük, nem pollozniuk

Minden beleegyezéstől függő script — hirdetési tag, analitikai loader, header bidding wrapper — két dolgot kell tudjon: van-e már döntése a CMP-nek, és mi az a döntés. Gyakori hiba, hogy oldalbetöltéskor kiolvasnak egy cookie-t, vagy időzítővel pollozzák a CMP-t, amíg meg nem jelenik valami. Mindkét megoldás kiszámítható módon romlik el: a cookie formátuma a CMP belső ügye, és változhat, a polling pedig vagy túl korán fut le, vagy feleslegesen vár.

Az IAB TCF pontosan erre a feladatra szabványos JavaScript-interfészt definiál: a __tcfapi függvényt. Ez az útmutató bemutatja a valóban szükséges parancsokat, a kapott eseményeket és az éles környezetben leggyakrabban előforduló hibákat.

A stub és a sor

A TCF-es CMP-től elvárt, hogy a lehető legkorábban, a teljes CMP-script betöltése előtt egy kis stubot helyezzen el az oldalon. A stub definiálja a window.__tcfapi-t, és sorba állítja a CMP készenléte előtt érkező hívásokat. Amikor a CMP befejezi a betöltést, feldolgozza a sort, és minden hívásra válaszol.

Ettől biztonságos, hogy más scriptek azonnal hívják a __tcfapi-t: amíg a stub előttük van az oldalon, a hívásaik nem vesznek el. Ha egy script hibát dob, mert a __tcfapi nincs definiálva, a stub vagy hiányzik, vagy túl későn töltődik be — a betöltési sorrendet javítsa, ne újrapróbálkozásokat adjon hozzá.

A fontos parancsok

ping

A __tcfapi('ping', 2, callback) alapvető állapotot ad vissza anélkül, hogy a felhasználó döntésére várna. A válasz tartalmazza a cmpLoaded-et, egy cmpStatus-t (például stub, loading, loaded vagy error), valamint egy displayStatus-t (visible, hidden vagy disabled). Ha már ismert, a gdprApplies-t is jelzi. Használja diagnosztikára, és annak eldöntésére, hogy a TCF egyáltalán releváns-e az adott látogatónál.

addEventListener

A __tcfapi('addEventListener', 2, callback) az a parancs, amelyet a legtöbb integrációnak használnia kell. A callback egy tcData objektumot és egy sikerjelzőt kap, és a beleegyezési állapot minden változásakor újra meghívódik. A TCF v2.2 óta ez az ajánlott módja a beleegyezési adatok megszerzésének; a régebbi getTCData parancsot elavultnak nyilvánították.

removeEventListener

Minden tcData objektum tartalmaz egy listenerId-t. Adja át a __tcfapi('removeEventListener', 2, callback, listenerId) hívásnak, amikor a scriptnek már nincs szüksége frissítésekre — például egy egyszeri loadernél, amely már meghozta a döntését.

Az eventStatus olvasása

A tcData kulcsmezője az eventStatus. Három értéke van:

• tcloaded — a CMP érvényes tárolt döntést talált, és nem jelenik meg banner. Az adatok alapján azonnal cselekedhet.
• cmpuishown — a banner megjelenik. Az adatok az esetleges korábbi állapotot tükrözik, de a felhasználó éppen módosíthatja azt.
• useractioncomplete — a felhasználó épp most hozott vagy erősített meg egy választást. Az új adatok alapján cselekedjen.

Egy tipikus loader a tcloaded vagy a useractioncomplete eseményre vár, majd ellenőrzi a szükséges célokat és szállítókat. A cmpuishown-t figyelmen kívül hagyja, legfeljebb naplózza, hogy megjelent a banner.

Célok és szállítók ellenőrzése

A tcData-n belül a beleegyezés és a jogos érdek azonosítóval indexelt objektumként érhető el:

• tcData.purpose.consents[1] — beleegyezés az 1. célhoz (eszköztárolás).
• tcData.purpose.legitimateInterests[7] — a jogos érdek állapota a 7. célhoz.
• tcData.vendor.consents[ID] és tcData.vendor.legitimateInterests[ID] — szállítónkénti állapot, a szállító Global Vendor List-beli azonosítójával.
• tcData.gdprApplies — megállapította-e a CMP, hogy a GDPR vonatkozik erre a látogatóra. Ha false, a scriptnek a nem TCF-es logikáját kell követnie.
• tcData.tcString — a kódolt string, amelyet továbbad az azt váró partnereknek.

Ellenőrizze a célt és a szállítót is. A szállító beleegyezése nélküli célbeleegyezés, vagy fordítva, a legtöbb szállítónak nem elég az adatkezeléshez.

Iframe-ek és keretek közötti hívások

A hirdetések és widgetek gyakran olyan iframe-ekben futnak, amelyek nem látják a szülőoldal __tcfapi-ját. A TCF ezt egy postMessage protokollal oldja meg: a CMP egy __tcfapiLocator nevű keretet ad a felső oldalhoz, és az iframe-ben futó kód megkeresheti, küldhet egy __tcfapiCall üzenetet, és kaphat egy __tcfapiReturn választ. A legtöbb hirdetési SDK ezt már megteszi. Ha saját iframe-kódot ír, ugyanezt a mintát valósítsa meg a cookie-k keretek közötti olvasása helyett.

Gyakori hibák és felismerésük

1. Cselekvés a cmpuishown alapján. Azok a scriptek, amelyek bármelyik callback lefutásakor betöltődnek, a felhasználó döntése előtt futnak le. Szűrjön az eventStatus szerint.
2. A figyelő túl korai eltávolítása. Ha az első callback után eltávolítja, lemarad egy későbbi useractioncomplete-ről, és a script soha nem tölt be.
3. A visszavonások figyelmen kívül hagyása. A tartósan futó scripteknek tovább kell figyelniük, és a beleegyezés visszavonásakor le kell állniuk vagy át kell konfigurálniuk magukat.
4. A gdprApplies figyelmen kívül hagyása. A TCF-régiókon kívül a cél objektumok üresek lehetnek; ha ezt “nincs beleegyezés”-nek tekinti, kikapcsolhat olyan bevételt, amelyet megszerezhetne.
5. A sikerjelző ellenőrzésének elmulasztása. Ha a success false, naplózza; általában elromlott CMP-beállításra utal.

Az integráció tesztelése

A böngészőkonzolban hívja meg a __tcfapi('ping', 2, console.log)-ot, hogy megerősítse a CMP jelenlétét, majd regisztráljon egy figyelőt console.log callbackkel, és kattintson végig a banneren. Első látogatáskor cmpuishown-t, majd useractioncomplete-et kell látnia, újratöltéskor tcloaded-et. Ismételje meg mindent elfogadva, mindent elutasítva és egyéni választással, és ellenőrizze, hogy a script mindegyik esetben helyesen viselkedik.

Legfontosabb tanulságok

• Használja a __tcfapi-t a CMP-cookie-k olvasása vagy a polling helyett.
• Gondoskodjon róla, hogy a CMP stub minden, az API-t hívó script előtt betöltődjön.
• Használja az addEventListener-t, és csak tcloaded vagy useractioncomplete esetén cselekedjen.
• Ellenőrizze a cél és a szállító állapotát is, és vegye figyelembe a gdprApplies-t.
• Iframe-ekben használja a __tcfapiLocator postMessage mintát.