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

  1. 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.
  2. 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.
  3. 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:

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

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

Viktigaste lärdomarna

← Blogg Läs allt →