Samtykke i cross-origin-iframes: mønstret med __tcfapiLocator og __gppLocator
Problemet: samtykke bor i det øverste vindue
En CMP kører på din side, i vinduet på øverste niveau. Meget af din annoncering gør ikke. Display-creatives, rich media, renderere til header bidding og mange tredjepartswidgets kører i iframes, ofte på en anden origin. Kode i en cross-origin-iframe kan ikke kalde en funktion på den overordnede side direkte og kan derfor ikke blot kalde __tcfapi eller __gpp og læse den besøgendes valg.
IAB's frameworks løser det med en lille, veldefineret beskedkonvention. Hvis du bygger annonceprodukter, embeds eller målescripts, der kører i frames, eller fejlsøger annoncestacks, der gør, er det værd at vide præcis, hvordan den virker.
Locator-framen
Ved siden af JavaScript-API'et tilføjer en TCF-CMP en tom, usynlig iframe ved navn __tcfapiLocator til siden på øverste niveau. En GPP-CMP gør det samme med en frame ved navn __gppLocator. Framene har intet indhold. Deres eneste opgave er at kunne findes: ethvert script i enhver indlejret frame kan gå opad i vinduehierarkiet og på hvert niveau tjekke, om der findes en frame med det navn.
Fordi framenavne er synlige på tværs af origins via window.frames, kan et script i en dybt indlejret cross-origin-iframe finde det vindue, der rummer CMP'en, uden at have adgang til andet på den side.
Hvordan et script i en frame finder CMP'en
- Start med det aktuelle vindue. Hvis __tcfapi findes lokalt, så brug det direkte — scriptet er ikke i en frame, eller framen deler CMP'en.
- Ellers gå opad i en løkke: tjek, om det aktuelle vindue indeholder en frame ved navn __tcfapiLocator; hvis ikke, gå til window.parent og tjek igen, indtil du når det øverste vindue.
- Når locatoren er fundet, er det vindue, der indeholder den, CMP'ens vindue. Kommunikationen sker nu via postMessage.
Pak hver adgang ind i try/catch, fordi nogle browsere eller sandbox-indstillinger kaster en fejl ved cross-origin-adgang til egenskaber, og stop løkken, når window.parent er lig med det aktuelle vindue.
Beskedformatet
For TCF sender scriptet i framen en besked til CMP-vinduet med et objekt, der har en egenskab __tcfapiCall. Heri ligger fire felter:
- command — for eksempel getTCData, ping eller addEventListener;
- parameter — ethvert argument, kommandoen har brug for, eller null;
- version — API-versionen, 2 for TCF v2;
- callId — en unik værdi genereret af kalderen.
CMP'en lytter efter disse beskeder, kører kommandoen og sender et objekt tilbage med en egenskab __tcfapiReturn, der indeholder returnValue, success og samme callId. Kalderen fører et map over ventende callbacks med callId som nøgle, lytter efter message-hændelser og sender hvert svar videre til den rette callback. GPP følger samme mønster med __gppCall og __gppReturn.
Mange integrationer skriver en lille proxy: en lokal funktion ved navn __tcfapi i framen, der oversætter kald til beskeder. Kode skrevet til det øverste vindue virker så uændret inde i framen.
Event listeners på tværs af frames
Et addEventListener-kald sendt via postMessage er ikke en engangsanmodning. CMP'en sender en returbesked hver gang samtykketilstanden ændres, alle med samme callId. Din dispatcher skal derfor holde den callback registreret i stedet for at slette den efter det første svar. At glemme det er en klassisk fejl: scriptet i framen læser samtykket én gang og opdager aldrig en senere tilbagetrækning.
Sikkerhedsovervejelser
- Validér beskedens form. Ignorér enhver besked, der ikke indeholder den forventede egenskab, og parse streng-payloads defensivt, da nogle implementeringer sender JSON-strenge frem for objekter.
- Stol ikke blindt. Enhver side kan sende beskeder til din frame. Behandl svar som samtykkesignaler, der skal respekteres, ikke som autentificerede data, og lad dem aldrig udløse privilegerede handlinger.
- Brug specifikke mål-origins, hvor du kan. Når CMP'ens origin er kendt, så send til den frem for til alle origins.
Hvor mønstret ikke rækker
Nogle annoncemiljøer isolerer creatives strengere. SafeFrame-containere, sandboxede iframes uden de rette tilladelser og creatives, der renderes i separate dokumenter, kan måske ikke gennemløbe frametræet eller modtage beskeder. I de tilfælde skal samtykkesignalet som regel gives eksplicit videre, for eksempel som parametre på annonceanmodningen eller værdier, adserveren overdrager til creativen, såsom parametrene gdpr og gdpr_consent, som mange annoncetags understøtter.
Fejlsøgningstjekliste
- Bekræft i DevTools i det øverste vindue, at locator-framene findes i panelet Elements.
- Skift konsolkontekst til iframen og tjek, om locatoren kan nås derfra.
- Log indkommende message-hændelser i begge vinduer for at bekræfte, at kald og svar flyder.
- Ændr samtykket i banneret og verificér, at listeners i frames modtager en opdatering.
- Test med CMP'en indlæst sent, for at sikre at kode i frames prøver igen eller venter i stedet for at give op med det samme.
Vigtigste pointer
- Cross-origin-frames når CMP'en via framene __tcfapiLocator og __gppLocator.
- Kald og svar bruger postMessage med __tcfapiCall/__tcfapiReturn eller GPP-ækvivalenterne, matchet via callId.
- Hold listener-callbacks registreret, så senere samtykkeændringer når frem.
- Validér hver besked og behandl den ikke som betroet input.
- Hvor frames er fuldt isolerede, giv samtykke eksplicit videre på annonceanmodningen.