Samtykke i cross-origin-iframes: mønsteret med __tcfapiLocator og __gppLocator
Problemet: samtykke bor i det øverste vinduet
En CMP kjører på siden din, i vinduet på øverste nivå. Mye av annonseringen din gjør ikke det. Display-creatives, rich media, rendere for header bidding og mange tredjepartswidgets kjører i iframes, ofte på en annen origin. Kode i en cross-origin-iframe kan ikke kalle en funksjon på den overordnede siden direkte, og kan derfor ikke bare kalle __tcfapi eller __gpp og lese den besøkendes valg.
IAB-rammeverkene løser dette med en liten, veldefinert meldingskonvensjon. Hvis du bygger annonseprodukter, embeds eller målingsskript som kjører i frames, eller feilsøker annonsestacker som gjør det, er det verdt å vite nøyaktig hvordan den fungerer.
Locator-framen
Ved siden av JavaScript-API-et legger en TCF-CMP til en tom, usynlig iframe med navnet __tcfapiLocator på siden på øverste nivå. En GPP-CMP gjør det samme med en frame med navnet __gppLocator. Framene har intet innhold. Deres eneste oppgave er å kunne bli funnet: ethvert skript i enhver nøstet frame kan gå oppover i vindushierarkiet og på hvert nivå sjekke om det finnes en frame med det navnet.
Fordi framenavn er synlige på tvers av origins via window.frames, kan et skript i en dypt nøstet cross-origin-iframe finne vinduet som rommer CMP-en, uten å ha tilgang til noe annet på den siden.
Hvordan et skript i en frame finner CMP-en
- Begynn med det gjeldende vinduet. Hvis __tcfapi finnes lokalt, bruk det direkte — skriptet er ikke i en frame, eller framen deler CMP-en.
- Ellers gå oppover i en løkke: sjekk om det gjeldende vinduet inneholder en frame med navnet __tcfapiLocator; hvis ikke, gå til window.parent og sjekk på nytt, til du når det øverste vinduet.
- Når locatoren er funnet, er vinduet som inneholder den, CMP-ens vindu. Kommunikasjonen skjer nå via postMessage.
Pakk hver tilgang inn i try/catch, fordi enkelte nettlesere eller sandbox-innstillinger kaster en feil ved cross-origin-tilgang til egenskaper, og stopp løkken når window.parent er lik det gjeldende vinduet.
Meldingsformatet
For TCF sender skriptet i framen en melding til CMP-vinduet med et objekt som har en egenskap __tcfapiCall. Her ligger fire felt:
- command — for eksempel getTCData, ping eller addEventListener;
- parameter — ethvert argument kommandoen trenger, eller null;
- version — API-versjonen, 2 for TCF v2;
- callId — en unik verdi generert av kalleren.
CMP-en lytter etter disse meldingene, kjører kommandoen og sender tilbake et objekt med en egenskap __tcfapiReturn som inneholder returnValue, success og samme callId. Kalleren fører et map over ventende callbacks med callId som nøkkel, lytter etter message-hendelser og sender hvert svar videre til riktig callback. GPP følger samme mønster med __gppCall og __gppReturn.
Mange integrasjoner skriver en liten proxy: en lokal funksjon med navnet __tcfapi i framen som oversetter kall til meldinger. Kode skrevet for det øverste vinduet fungerer da uendret inne i framen.
Event listeners på tvers av frames
Et addEventListener-kall sendt via postMessage er ikke en engangsforespørsel. CMP-en sender en returmelding hver gang samtykketilstanden endres, alle med samme callId. Dispatcheren din må derfor beholde den callbacken registrert i stedet for å slette den etter det første svaret. Å glemme dette er en klassisk feil: skriptet i framen leser samtykket én gang og oppdager aldri en senere tilbaketrekking.
Sikkerhetshensyn
- Valider meldingens form. Ignorer enhver melding som ikke inneholder den forventede egenskapen, og parse streng-payloads defensivt, siden noen implementeringer sender JSON-strenger i stedet for objekter.
- Ikke stol blindt. Enhver side kan sende meldinger til framen din. Behandle svar som samtykkesignaler som skal respekteres, ikke som autentiserte data, og la dem aldri utløse privilegerte handlinger.
- Bruk spesifikke mål-origins der du kan. Når CMP-ens origin er kjent, send til den i stedet for til alle origins.
Hvor mønsteret ikke rekker
Noen annonsemiljøer isolerer creatives strengere. SafeFrame-containere, sandboxede iframes uten de rette tillatelsene og creatives som rendres i separate dokumenter kan kanskje ikke gå gjennom frametreet eller motta meldinger. I slike tilfeller må samtykkesignalet vanligvis gis videre eksplisitt, for eksempel som parametere på annonseforespørselen eller verdier annonseserveren overleverer til creativen, som parameterne gdpr og gdpr_consent som mange annonsetagger støtter.
Feilsøkingssjekkliste
- Bekreft i DevTools i det øverste vinduet at locator-framene finnes i panelet Elements.
- Bytt konsollkontekst til iframen og sjekk om locatoren kan nås derfra.
- Logg innkommende message-hendelser i begge vinduene for å bekrefte at kall og svar flyter.
- Endre samtykket i banneret og verifiser at listeners i frames mottar en oppdatering.
- Test med CMP-en lastet sent, for å sikre at kode i frames prøver på nytt eller venter i stedet for å gi opp med en gang.
Viktigste poenger
- Cross-origin-frames når CMP-en via framene __tcfapiLocator og __gppLocator.
- Kall og svar bruker postMessage med __tcfapiCall/__tcfapiReturn eller GPP-ekvivalentene, koblet via callId.
- Behold listener-callbacks registrert slik at senere samtykkeendringer kommer fram.
- Valider hver melding og behandle den ikke som pålitelig inndata.
- Der frames er fullstendig isolert, gi samtykke eksplisitt videre på annonseforespørselen.