Samtycke i cross-origin-iframes: mönstret med __tcfapiLocator och __gppLocator
Problemet: samtycket bor i det översta fönstret
En CMP körs på din sida, i fönstret på högsta nivå. Mycket av din annonsering gör det inte. Displaykreativ, rich media, renderare för header bidding och många tredjepartswidgets körs i iframes, ofta på en annan origin. Kod i en cross-origin-iframe kan inte anropa en funktion på föräldersidan direkt, så den kan inte bara anropa __tcfapi eller __gpp och läsa besökarens val.
IAB:s ramverk löser detta med en liten, väldefinierad meddelandekonvention. Om du bygger annonsprodukter, inbäddningar eller mätskript som körs i ramar, eller felsöker annonsstackar som gör det, är det värt att veta exakt hur det fungerar.
Locator-ramen
Vid sidan av JavaScript-API:et lägger en TCF-CMP till en tom, osynlig iframe med namnet __tcfapiLocator på sidan på högsta nivå. En GPP-CMP gör detsamma med en ram som heter __gppLocator. Ramarna har inget innehåll. Deras enda uppgift är att kunna hittas: alla skript i alla nästlade ramar kan gå uppåt i fönsterhierarkin och på varje nivå kontrollera om en ram med det namnet finns.
Eftersom ramnamn är synliga över origins via window.frames kan ett skript i en djupt nästlad cross-origin-iframe hitta fönstret som är värd för CMP:n utan att ha åtkomst till något annat på den sidan.
Så hittar ett inramat skript CMP:n
- Börja med det aktuella fönstret. Om __tcfapi finns lokalt, använd den direkt — skriptet ligger inte i en ram, eller så delar ramen CMP:n.
- Annars, loopa uppåt: kontrollera om det aktuella fönstret innehåller en ram med namnet __tcfapiLocator; om inte, gå till window.parent och kontrollera igen, och stanna vid det översta fönstret.
- När locatorn hittas är fönstret som innehåller den CMP:ns fönster. Kommunikationen sker nu via postMessage.
Slå in varje åtkomst i try/catch, eftersom vissa webbläsare eller sandlådeinställningar kastar fel vid cross-origin-åtkomst av egenskaper, och stoppa loopen när window.parent är lika med det aktuella fönstret.
Meddelandeformatet
För TCF postar det inramade skriptet ett meddelande till CMP-fönstret som innehåller ett objekt med egenskapen __tcfapiCall. Inuti finns fyra fält:
- command — till exempel getTCData, ping eller addEventListener;
- parameter — eventuellt argument som kommandot behöver, eller null;
- version — API-versionen, 2 för TCF v2;
- callId — ett unikt värde som genereras av anroparen.
CMP:n lyssnar efter dessa meddelanden, kör kommandot och postar tillbaka ett objekt med egenskapen __tcfapiReturn som innehåller returnValue, success och samma callId. Anroparen håller en karta över väntande callbacks med callId som nyckel, lyssnar efter message-händelser och skickar varje retur till rätt callback. GPP följer samma mönster med __gppCall och __gppReturn.
Många integrationer skriver en liten proxy: en lokal funktion med namnet __tcfapi inuti ramen som översätter anrop till meddelanden. Kod som skrivits för det översta fönstret fungerar då oförändrad inuti ramen.
Event listeners över ramar
Ett addEventListener-anrop som skickas via postMessage är inte en engångsförfrågan. CMP:n postar ett returmeddelande varje gång samtyckestillståndet ändras, alla med samma callId. Din dispatcher måste därför hålla den callbacken registrerad i stället för att ta bort den efter det första svaret. Att glömma detta är ett klassiskt fel: det inramade skriptet läser samtycket en gång och märker aldrig en senare återkallelse.
Säkerhetsöverväganden
- Validera meddelandets form. Ignorera alla meddelanden som inte innehåller den förväntade egenskapen och tolka strängnyttolaster defensivt, eftersom vissa implementeringar skickar JSON-strängar i stället för objekt.
- Lita inte blint. Vilken sida som helst kan posta meddelanden till din ram. Behandla svar som samtyckessignaler att respektera, inte som autentiserad data, och låt dem aldrig utlösa privilegierade åtgärder.
- Använd specifika målorigins när du kan. När CMP:ns origin är känd, posta till den i stället för till alla origins.
Där mönstret inte når
Vissa annonsmiljöer isolerar kreativ strängare. SafeFrame-containrar, sandlådade iframes utan rätt behörigheter och kreativ som renderas i separata dokument kanske inte kan gå igenom ramträdet eller ta emot meddelanden. I de fallen måste samtyckessignalen vanligtvis skickas uttryckligen, till exempel som parametrar i annonsförfrågan eller värden som annonsservern lämnar till kreativet, såsom parametrarna gdpr och gdpr_consent som många annonstaggar stöder.
Felsökningschecklista
- Bekräfta i det översta fönstrets DevTools att locator-ramarna finns i panelen Elements.
- Byt konsolkontext till iframen och kontrollera om locatorn kan nås därifrån.
- Logga inkommande message-händelser i båda fönstren för att bekräfta att anrop och returer flödar.
- Ändra samtycke i bannern och verifiera att inramade listeners får en uppdatering.
- Testa med en sent laddad CMP för att säkerställa att inramad kod försöker igen eller väntar i stället för att ge upp direkt.
Viktigaste lärdomarna
- Cross-origin-ramar når CMP:n via ramarna __tcfapiLocator och __gppLocator.
- Anrop och returer använder postMessage med __tcfapiCall/__tcfapiReturn eller GPP-motsvarigheterna, matchade via callId.
- Håll listener-callbacks registrerade så att senare samtyckesändringar når fram.
- Validera varje meddelande och behandla det inte som betrodd indata.
- Där ramar är helt isolerade, skicka samtycke uttryckligen i annonsförfrågan.