Waarom je scripts moeten luisteren in plaats van pollen

Elk script dat van toestemming afhangt — een advertentietag, een analytics-loader, een header bidding-wrapper — moet twee dingen weten: of de CMP al een beslissing heeft en wat die beslissing is. Een veelgemaakte fout is om bij het laden van de pagina een cookie te lezen, of de CMP met een timer te pollen tot er iets verschijnt. Beide aanpakken falen op voorspelbare wijze: het cookieformaat is intern aan de CMP en kan veranderen, en polling vuurt ofwel te vroeg af of verspilt wachttijd.

De IAB TCF definieert voor precies deze taak een standaard JavaScript-interface: de functie __tcfapi. Deze tutorial doorloopt de commando's die je echt nodig hebt, de events die je ontvangt en de bugs die in productie het vaakst voorkomen.

De stub en de wachtrij

Een TCF-CMP hoort zo vroeg mogelijk een kleine stub op de pagina te plaatsen, voordat het volledige CMP-script laadt. De stub definieert window.__tcfapi en zet alle aanroepen in de wachtrij die worden gedaan voordat de CMP klaar is. Zodra de CMP klaar is met laden, verwerkt hij de wachtrij en beantwoordt hij elke aanroep.

Daardoor kunnen andere scripts __tcfapi veilig meteen aanroepen: zolang de stub vóór hen op de pagina staat, gaan hun aanroepen niet verloren. Als een script een fout gooit omdat __tcfapi niet gedefinieerd is, ontbreekt de stub of laadt hij te laat — los de laadvolgorde op in plaats van herhaalpogingen toe te voegen.

De commando's die ertoe doen

ping

__tcfapi('ping', 2, callback) geeft basisstatus terug zonder op een beslissing van de gebruiker te wachten. Het antwoord bevat cmpLoaded, een cmpStatus zoals stub, loading, loaded of error, en een displayStatus van visible, hidden of disabled. Het meldt ook gdprApplies zodra dat bekend is. Gebruik het voor diagnose en om te bepalen of de TCF voor deze bezoeker überhaupt relevant is.

addEventListener

__tcfapi('addEventListener', 2, callback) is het commando dat de meeste integraties zouden moeten gebruiken. De callback ontvangt een tcData-object en een succesvlag, en wordt opnieuw aangeroepen telkens als de toestemmingsstatus verandert. Sinds TCF v2.2 is dit de aanbevolen manier om toestemmingsgegevens te krijgen; het oudere commando getTCData is verouderd verklaard.

removeEventListener

Elk tcData-object bevat een listenerId. Geef die door aan __tcfapi('removeEventListener', 2, callback, listenerId) wanneer je script geen updates meer nodig heeft — bijvoorbeeld een eenmalige loader die zijn beslissing al heeft genomen.

De eventStatus lezen

Het sleutelveld in tcData is eventStatus. Er zijn drie waarden:

• tcloaded — de CMP heeft een geldige opgeslagen beslissing gevonden en er wordt geen banner getoond. Je kunt direct op de gegevens handelen.
• cmpuishown — de banner wordt getoond. De gegevens weerspiegelen een eventuele eerdere status, maar de gebruiker staat misschien op het punt die te wijzigen.
• useractioncomplete — de gebruiker heeft zojuist een keuze gemaakt of bevestigd. Handel op de nieuwe gegevens.

Een typische loader wacht op tcloaded of useractioncomplete en controleert dan de doelen en vendors die hij nodig heeft. Hij negeert cmpuishown, behalve misschien om te loggen dat er een banner verscheen.

Doelen en vendors controleren

In tcData worden toestemming en gerechtvaardigd belang beschikbaar gesteld als objecten met ID's als sleutel:

• tcData.purpose.consents[1] — toestemming voor doel 1 (opslag op het apparaat).
• tcData.purpose.legitimateInterests[7] — status van gerechtvaardigd belang voor doel 7.
• tcData.vendor.consents[ID] en tcData.vendor.legitimateInterests[ID] — status per vendor, met het ID van de vendor in de Global Vendor List.
• tcData.gdprApplies — of de CMP heeft vastgesteld dat de AVG op deze bezoeker van toepassing is. Is dit false, dan moet je script zijn niet-TCF-logica volgen.
• tcData.tcString — de gecodeerde string, die je doorgeeft aan partners die hem verwachten.

Controleer zowel het doel als de vendor. Een doeltoestemming zonder vendortoestemming, of andersom, is voor de meeste vendors niet genoeg om gegevens te verwerken.

Iframes en cross-frame-aanroepen

Advertenties en widgets draaien vaak in iframes die de __tcfapi van de bovenliggende pagina niet kunnen zien. De TCF lost dit op met een postMessage-protocol: de CMP voegt een frame genaamd __tcfapiLocator toe aan de bovenste pagina, en code in een iframe kan dat vinden, een __tcfapiCall-bericht sturen en een __tcfapiReturn-antwoord ontvangen. De meeste advertentie-SDK's doen dit al. Als je zelf iframecode schrijft, implementeer dan hetzelfde patroon in plaats van cookies over frames heen te lezen.

Veelvoorkomende bugs en hoe je ze herkent

1. Handelen op cmpuishown. Scripts die laden zodra een callback afgaat, draaien voordat de gebruiker heeft beslist. Filter op eventStatus.
2. De listener te vroeg verwijderen. Als je hem na de eerste callback verwijdert, mis je een latere useractioncomplete en laadt het script nooit.
3. Intrekkingen negeren. Blijvende scripts moeten blijven luisteren en zichzelf stoppen of herconfigureren wanneer toestemming wordt ingetrokken.
4. gdprApplies negeren. Buiten TCF-regio's kunnen de doelobjecten leeg zijn; dat behandelen als “geen toestemming” kan inkomsten uitschakelen die je mag verdienen.
5. De succesvlag niet controleren. Wanneer success false is, log dat dan; het wijst meestal op een kapotte CMP-configuratie.

Je integratie testen

Roep in de browserconsole __tcfapi('ping', 2, console.log) aan om te bevestigen dat de CMP aanwezig is, registreer dan een listener met console.log als callback en klik door de banner. Je zou bij een eerste bezoek cmpuishown gevolgd door useractioncomplete moeten zien, en tcloaded na een herlaad. Herhaal dit met alles accepteren, alles weigeren en een aangepaste selectie, en controleer of je script zich in elk geval correct gedraagt.

Belangrijkste punten

• Gebruik __tcfapi in plaats van CMP-cookies te lezen of te pollen.
• Zorg dat de CMP-stub laadt vóór elk script dat de API aanroept.
• Gebruik addEventListener en handel alleen op tcloaded of useractioncomplete.
• Controleer zowel doel- als vendorstatus en respecteer gdprApplies.
• Gebruik het postMessage-patroon met __tcfapiLocator binnen iframes.