Hvorfor dine scripts bør lytte i stedet for at polle

Ethvert script, der afhænger af samtykke — et annoncetag, en analytics-loader, en header bidding-wrapper — skal vide to ting: om CMP'en har en beslutning endnu, og hvad den beslutning er. En almindelig fejl er at læse en cookie ved sideindlæsning eller at polle CMP'en med en timer, indtil noget dukker op. Begge tilgange svigter på forudsigelige måder: cookieformatet er internt i CMP'en og kan ændre sig, og polling affyrer enten for tidligt eller spilder ventetid.

IAB TCF definerer en standard JavaScript-grænseflade til netop dette job: funktionen __tcfapi. Denne tutorial gennemgår de kommandoer, du reelt har brug for, de events, du modtager, og de fejl, der oftest viser sig i produktion.

Stubben og køen

En TCF-CMP forventes at placere en lille stub på siden så tidligt som muligt, før det fulde CMP-script indlæses. Stubben definerer window.__tcfapi og sætter alle kald, der foretages, før CMP'en er klar, i kø. Når CMP'en er færdig med at indlæse, behandler den køen og besvarer hvert kald.

Det er det, der gør det sikkert for andre scripts at kalde __tcfapi med det samme: så længe stubben er på siden før dem, går deres kald ikke tabt. Hvis et script kaster en fejl, fordi __tcfapi er udefineret, mangler stubben eller indlæses for sent — ret indlæsningsrækkefølgen i stedet for at tilføje genforsøg.

De kommandoer, der betyder noget

ping

__tcfapi('ping', 2, callback) returnerer grundlæggende status uden at vente på en brugerbeslutning. Svaret indeholder cmpLoaded, en cmpStatus som stub, loading, loaded eller error og en displayStatus med visible, hidden eller disabled. Det rapporterer også gdprApplies, når den er kendt. Brug det til diagnostik og til at afgøre, om TCF overhovedet er relevant for denne besøgende.

addEventListener

__tcfapi('addEventListener', 2, callback) er den kommando, de fleste integrationer bør bruge. Callbacken modtager et tcData-objekt og et succesflag og kaldes igen hver gang samtykketilstanden ændres. Siden TCF v2.2 er dette den anbefalede måde at få samtykkedata på; den ældre kommando getTCData blev udfaset.

removeEventListener

Hvert tcData-objekt bærer et listenerId. Send det til __tcfapi('removeEventListener', 2, callback, listenerId), når dit script ikke længere har brug for opdateringer — for eksempel en engangsloader, der allerede har truffet sin beslutning.

Aflæsning af eventStatus

Nøglefeltet i tcData er eventStatus. Der er tre værdier:

• tcloaded — CMP'en fandt en gyldig gemt beslutning, og intet banner vil blive vist. Du kan handle på dataene med det samme.
• cmpuishown — banneret vises. Dataene afspejler en eventuel tidligere tilstand, men brugeren er måske ved at ændre den.
• useractioncomplete — brugeren har netop truffet eller bekræftet et valg. Handl på de nye data.

En typisk loader venter på enten tcloaded eller useractioncomplete og tjekker derefter de formål og leverandører, den har brug for. Den ignorerer cmpuishown, bortset fra måske at logge, at et banner dukkede op.

Kontrol af formål og leverandører

Inde i tcData er samtykke og legitim interesse eksponeret som objekter med ID som nøgle:

• tcData.purpose.consents[1] — samtykke til formål 1 (lagring på enheden).
• tcData.purpose.legitimateInterests[7] — status for legitim interesse for formål 7.
• tcData.vendor.consents[ID] og tcData.vendor.legitimateInterests[ID] — status pr. leverandør, med leverandørens ID i Global Vendor List.
• tcData.gdprApplies — om CMP'en har fastslået, at GDPR gælder for denne besøgende. Hvis den er false, bør dit script følge sin ikke-TCF-logik.
• tcData.tcString — den kodede streng, som du videregiver til partnere, der forventer den.

Tjek både formålet og leverandøren. Et formålssamtykke uden leverandørsamtykke, eller omvendt, er ikke nok for de fleste leverandører til at behandle data.

Iframes og kald på tværs af frames

Annoncer og widgets kører ofte i iframes, der ikke kan se den overordnede sides __tcfapi. TCF løser det med en postMessage-protokol: CMP'en tilføjer en frame ved navn __tcfapiLocator til topsiden, og kode i en iframe kan finde den, sende en __tcfapiCall-besked og modtage et __tcfapiReturn-svar. De fleste annonce-SDK'er gør allerede dette. Hvis du selv skriver iframe-kode, så implementér det samme mønster i stedet for at læse cookies på tværs af frames.

Almindelige fejl og hvordan du opdager dem

1. At handle på cmpuishown. Scripts, der indlæses, så snart en callback affyres, kører, før brugeren har besluttet sig. Filtrér på eventStatus.
2. At fjerne listeneren for tidligt. Hvis du fjerner den efter den første callback, går du glip af en senere useractioncomplete og indlæser aldrig.
3. At ignorere tilbagetrækninger. Vedvarende scripts bør blive ved med at lytte og stoppe eller omkonfigurere sig selv, når samtykket trækkes tilbage.
4. At ignorere gdprApplies. Uden for TCF-regioner kan formålsobjekterne være tomme; at behandle det som “intet samtykke” kan slukke for indtægter, du har lov til at tjene.
5. At undlade at tjekke succesflaget. Når success er false, så log det; det tyder som regel på en defekt CMP-opsætning.

Test af din integration

Kald __tcfapi('ping', 2, console.log) i browserkonsollen for at bekræfte, at CMP'en er til stede, registrér derefter en listener med console.log som callback og klik dig gennem banneret. Du bør se cmpuishown efterfulgt af useractioncomplete ved første besøg og tcloaded ved genindlæsning. Gentag med accepter alle, afvis alle og et brugerdefineret valg, og bekræft, at dit script opfører sig korrekt i hvert tilfælde.

Vigtigste pointer

• Brug __tcfapi i stedet for at læse CMP-cookies eller polle.
• Sørg for, at CMP-stubben indlæses før ethvert script, der kalder API'et.
• Brug addEventListener og handl kun på tcloaded eller useractioncomplete.
• Tjek både formåls- og leverandørstatus, og respektér gdprApplies.
• Brug postMessage-mønsteret med __tcfapiLocator inde i iframes.