Hvorfor skriptene dine bør lytte i stedet for å polle

Ethvert skript som avhenger av samtykke — en annonsetagg, en analytics-loader, en header bidding-wrapper — må vite to ting: om CMP-en har en beslutning ennå, og hva den beslutningen er. En vanlig feil er å lese en informasjonskapsel ved sideinnlasting, eller å polle CMP-en med en timer til noe dukker opp. Begge tilnærmingene svikter på forutsigbare måter: formatet på informasjonskapselen er internt i CMP-en og kan endre seg, og polling avfyres enten for tidlig eller kaster bort ventetid.

IAB TCF definerer et standard JavaScript-grensesnitt for akkurat denne jobben: funksjonen __tcfapi. Denne tutorialen går gjennom kommandoene du faktisk trenger, hendelsene du vil motta og feilene som oftest dukker opp i produksjon.

Stubben og køen

En TCF-CMP forventes å plassere en liten stub på siden så tidlig som mulig, før hele CMP-skriptet lastes. Stubben definerer window.__tcfapi og setter alle kall som gjøres før CMP-en er klar, i kø. Når CMP-en er ferdig lastet, behandler den køen og besvarer hvert kall.

Det er dette som gjør det trygt for andre skript å kalle __tcfapi umiddelbart: så lenge stubben er på siden før dem, går ikke kallene deres tapt. Hvis et skript kaster en feil fordi __tcfapi er udefinert, mangler stubben eller lastes for sent — rett opp innlastingsrekkefølgen i stedet for å legge til nye forsøk.

Kommandoene som betyr noe

ping

__tcfapi('ping', 2, callback) returnerer grunnleggende status uten å vente på en brukerbeslutning. Svaret inneholder cmpLoaded, en cmpStatus som stub, loading, loaded eller error, og en displayStatus med visible, hidden eller disabled. Det rapporterer også gdprApplies så snart den er kjent. Bruk det til diagnostikk og til å avgjøre om TCF i det hele tatt er relevant for denne besøkende.

addEventListener

__tcfapi('addEventListener', 2, callback) er kommandoen de fleste integrasjoner bør bruke. Callbacken mottar et tcData-objekt og et suksessflagg, og kalles på nytt hver gang samtykketilstanden endres. Siden TCF v2.2 er dette den anbefalte måten å hente samtykkedata på; den eldre kommandoen getTCData ble utfaset.

removeEventListener

Hvert tcData-objekt har en listenerId. Send den til __tcfapi('removeEventListener', 2, callback, listenerId) når skriptet ditt ikke lenger trenger oppdateringer — for eksempel en engangsloader som allerede har tatt sin beslutning.

Å lese eventStatus

Nøkkelfeltet i tcData er eventStatus. Det finnes tre verdier:

• tcloaded — CMP-en fant en gyldig lagret beslutning, og ingen banner vil bli vist. Du kan handle på dataene umiddelbart.
• cmpuishown — banneret vises. Dataene gjenspeiler en eventuell tidligere tilstand, men brukeren er kanskje i ferd med å endre den.
• useractioncomplete — brukeren har nettopp tatt eller bekreftet et valg. Handle på de nye dataene.

En typisk loader venter på enten tcloaded eller useractioncomplete, og sjekker deretter formålene og leverandørene den trenger. Den ignorerer cmpuishown, bortsett fra kanskje å logge at et banner dukket opp.

Kontroll av formål og leverandører

Inne i tcData er samtykke og berettiget interesse eksponert som objekter med ID som nøkkel:

• tcData.purpose.consents[1] — samtykke til formål 1 (lagring på enheten).
• tcData.purpose.legitimateInterests[7] — status for berettiget interesse for formål 7.
• tcData.vendor.consents[ID] og tcData.vendor.legitimateInterests[ID] — status per leverandør, med leverandørens ID i Global Vendor List.
• tcData.gdprApplies — om CMP-en har fastslått at GDPR gjelder for denne besøkende. Hvis den er false, bør skriptet ditt følge sin ikke-TCF-logikk.
• tcData.tcString — den kodede strengen, som du sender videre til partnere som forventer den.

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

Iframes og kall på tvers av frames

Annonser og widgets kjører ofte i iframes som ikke kan se den overordnede sidens __tcfapi. TCF løser dette med en postMessage-protokoll: CMP-en legger til en frame ved navn __tcfapiLocator på toppsiden, og kode inne i en iframe kan finne den, sende en __tcfapiCall-melding og motta et __tcfapiReturn-svar. De fleste annonse-SDK-er gjør dette allerede. Hvis du skriver egen iframe-kode, implementer det samme mønsteret i stedet for å lese informasjonskapsler på tvers av frames.

Vanlige feil og hvordan du oppdager dem

1. Å handle på cmpuishown. Skript som lastes så snart en callback avfyres, kjører før brukeren har bestemt seg. Filtrer på eventStatus.
2. Å fjerne listeneren for tidlig. Hvis du fjerner den etter den første callbacken, går du glipp av en senere useractioncomplete og laster aldri.
3. Å ignorere tilbaketrekninger. Vedvarende skript bør fortsette å lytte og stoppe eller omkonfigurere seg selv når samtykke trekkes tilbake.
4. Å ignorere gdprApplies. Utenfor TCF-regioner kan formålsobjektene være tomme; å behandle det som “ikke samtykke” kan slå av inntekter du har lov til å tjene.
5. Å ikke sjekke suksessflagget. Når success er false, logg det; det tyder vanligvis på et ødelagt CMP-oppsett.

Testing av integrasjonen

Kall __tcfapi('ping', 2, console.log) i nettleserkonsollen for å bekrefte at CMP-en er til stede, registrer deretter en listener med console.log som callback og klikk deg gjennom banneret. Du bør se cmpuishown etterfulgt av useractioncomplete ved første besøk, og tcloaded ved ny innlasting. Gjenta med godta alle, avvis alle og et egendefinert valg, og bekreft at skriptet ditt oppfører seg riktig i hvert tilfelle.

Viktigste poenger

• Bruk __tcfapi i stedet for å lese CMP-informasjonskapsler eller polle.
• Sørg for at CMP-stubben lastes før ethvert skript som kaller API-et.
• Bruk addEventListener og handle bare på tcloaded eller useractioncomplete.
• Sjekk både formåls- og leverandørstatus, og respekter gdprApplies.
• Bruk postMessage-mønsteret med __tcfapiLocator inne i iframes.