Varför dina skript ska lyssna, inte polla

Varje skript som är beroende av samtycke — en annonstagg, en analysladdare, ett header bidding-omslag — behöver veta två saker: om CMP:n har ett beslut ännu och vad det beslutet är. Ett vanligt misstag är att läsa en cookie vid sidladdning, eller att polla CMP:n med en timer tills något dyker upp. Båda tillvägagångssätten går sönder på förutsägbara sätt: cookiens format är internt för CMP:n och kan ändras, och pollning avfyras antingen för tidigt eller slösar tid på att vänta.

IAB TCF definierar ett standardiserat JavaScript-gränssnitt för just det här uppdraget: funktionen __tcfapi. Den här guiden går igenom de kommandon du faktiskt behöver, de händelser du får och de buggar som oftast dyker upp i produktion.

Stubben och kön

En TCF-CMP förväntas placera en liten stub på sidan så tidigt som möjligt, innan hela CMP-skriptet laddas. Stubben definierar window.__tcfapi och köar alla anrop som görs innan CMP:n är redo. När CMP:n har laddat klart bearbetar den kön och svarar på varje anrop.

Det är detta som gör det säkert för andra skript att anropa __tcfapi direkt: så länge stubben finns på sidan före dem går deras anrop inte förlorade. Om ett skript kastar ett fel eftersom __tcfapi är odefinierat saknas stubben eller laddas för sent — åtgärda laddningsordningen i stället för att lägga till omförsök.

De kommandon som räknas

ping

__tcfapi('ping', 2, callback) returnerar grundläggande status utan att vänta på ett användarbeslut. Svaret innehåller cmpLoaded, en cmpStatus såsom stub, loading, loaded eller error, och en displayStatus som är visible, hidden eller disabled. Den rapporterar också gdprApplies när det är känt. Använd den för diagnostik och för att avgöra om TCF över huvud taget är relevant för den här besökaren.

addEventListener

__tcfapi('addEventListener', 2, callback) är det kommando som de flesta integrationer bör använda. Callbacken får ett tcData-objekt och en framgångsflagga, och den anropas igen varje gång samtyckestillståndet ändras. Sedan TCF v2.2 är detta det rekommenderade sättet att hämta samtyckesdata; det äldre kommandot getTCData har fasats ut.

removeEventListener

Varje tcData-objekt bär ett listenerId. Skicka det till __tcfapi('removeEventListener', 2, callback, listenerId) när ditt skript inte längre behöver uppdateringar — till exempel en engångsladdare som redan har fattat sitt beslut.

Läsa eventStatus

Nyckelfältet i tcData är eventStatus. Det finns tre värden:

• tcloaded — CMP:n hittade ett giltigt lagrat beslut och ingen banner kommer att visas. Du kan agera på data direkt.
• cmpuishown — bannern visas. Data speglar eventuellt tidigare tillstånd, men användaren kan vara på väg att ändra det.
• useractioncomplete — användaren har just gjort eller bekräftat ett val. Agera på de nya data.

En typisk laddare väntar på antingen tcloaded eller useractioncomplete och kontrollerar sedan de ändamål och leverantörer den behöver. Den ignorerar cmpuishown, förutom kanske för att logga att en banner dök upp.

Kontrollera ändamål och leverantörer

Inuti tcData exponeras samtycke och berättigat intresse som objekt nycklade på ID:

• tcData.purpose.consents[1] — samtycke för ändamål 1 (lagring på enheten).
• tcData.purpose.legitimateInterests[7] — status för berättigat intresse för ändamål 7.
• tcData.vendor.consents[ID] och tcData.vendor.legitimateInterests[ID] — status per leverantör, med leverantörens ID i Global Vendor List.
• tcData.gdprApplies — om CMP:n har fastställt att GDPR gäller för den här besökaren. Om det är false bör ditt skript följa sin icke-TCF-logik.
• tcData.tcString — den kodade strängen, som du skickar vidare till partner som förväntar sig den.

Kontrollera både ändamålet och leverantören. Ett ändamålssamtycke utan leverantörssamtycke, eller tvärtom, räcker inte för de flesta leverantörer att behandla data.

Iframes och anrop mellan ramar

Annonser och widgets körs ofta i iframes som inte kan se föräldrasidans __tcfapi. TCF löser detta med ett postMessage-protokoll: CMP:n lägger till en ram med namnet __tcfapiLocator på toppsidan, och kod inuti en iframe kan hitta den, skicka ett __tcfapiCall-meddelande och ta emot ett __tcfapiReturn-svar. De flesta annons-SDK:er gör redan detta. Om du skriver egen iframe-kod, implementera samma mönster i stället för att läsa cookies mellan ramar.

Vanliga buggar och hur du upptäcker dem

1. Att agera på cmpuishown. Skript som laddas så fort någon callback avfyras körs innan användaren har bestämt sig. Filtrera på eventStatus.
2. Att ta bort lyssnaren för tidigt. Om du tar bort den efter den första callbacken missar du en senare useractioncomplete och laddar aldrig.
3. Att ignorera återkallanden. Beständiga skript bör fortsätta lyssna och stoppa eller konfigurera om sig när samtycke återkallas.
4. Att ignorera gdprApplies. Utanför TCF-regioner kan ändamålsobjekt vara tomma; att tolka det som “inget samtycke” kan stänga av intäkter du har rätt att tjäna.
5. Att inte kontrollera framgångsflaggan. När success är false, logga det; det signalerar oftast en trasig CMP-konfiguration.

Testa din integration

Anropa __tcfapi('ping', 2, console.log) i webbläsarkonsolen för att bekräfta att CMP:n finns, registrera sedan en lyssnare med console.log som callback och klicka dig igenom bannern. Du bör se cmpuishown följt av useractioncomplete vid ett första besök, och tcloaded vid en omladdning. Upprepa med acceptera alla, avvisa alla och ett anpassat val, och bekräfta att ditt skript beter sig korrekt i varje fall.

Viktiga slutsatser

• Använd __tcfapi i stället för att läsa CMP-cookies eller polla.
• Se till att CMP-stubben laddas före alla skript som anropar API:t.
• Använd addEventListener och agera bara på tcloaded eller useractioncomplete.
• Kontrollera både ändamåls- och leverantörsstatus, och respektera gdprApplies.
• Använd postMessage-mönstret med __tcfapiLocator inuti iframes.