Toestemming in cross-origin-iframes: het patroon __tcfapiLocator en __gppLocator

Het probleem: toestemming leeft in het bovenste venster

Een CMP draait op je pagina, in het venster op het hoogste niveau. Een groot deel van je advertenties niet. Display-creatives, rich media, renderers voor header bidding en veel widgets van derden draaien in iframes, vaak op een andere origin. Code in een cross-origin-iframe kan geen functie op de bovenliggende pagina rechtstreeks aanroepen en dus niet zomaar __tcfapi of __gpp aanroepen om de keuze van de bezoeker te lezen.

De IAB-frameworks lossen dit op met een kleine, goed gedefinieerde berichtenconventie. Als je advertentieproducten, embeds of meetscripts bouwt die in frames draaien, of advertentiestacks debugt die dat doen, is het de moeite waard precies te weten hoe het werkt.

Het locatorframe

Naast de JavaScript-API voegt een TCF-CMP een leeg, onzichtbaar iframe met de naam __tcfapiLocator toe aan de pagina op het hoogste niveau. Een GPP-CMP doet hetzelfde met een frame met de naam __gppLocator. De frames bevatten geen inhoud. Hun enige taak is vindbaar te zijn: elk script in elk geneste frame kan de vensterhiërarchie omhoog lopen en op elk niveau controleren of er een frame met die naam bestaat.

Omdat framenamen via window.frames over origins heen zichtbaar zijn, kan een script in een diep geneste cross-origin-iframe het venster vinden dat de CMP host, zonder toegang te hebben tot iets anders op die pagina.

Hoe een script in een frame de CMP vindt

  1. Begin met het huidige venster. Als __tcfapi lokaal bestaat, gebruik het dan rechtstreeks — het script staat niet in een frame, of het frame deelt de CMP.
  2. Loop anders omhoog: controleer of het huidige venster een frame met de naam __tcfapiLocator bevat; zo niet, ga dan naar window.parent en controleer opnieuw, tot je het bovenste venster bereikt.
  3. Zodra de locator is gevonden, is het venster dat hem bevat het venster van de CMP. De communicatie verloopt nu via postMessage.

Verpak elke toegang in een try/catch, omdat sommige browsers of sandboxinstellingen een fout geven bij cross-origin-eigenschapstoegang, en stop de lus wanneer window.parent gelijk is aan het huidige venster.

Het berichtformaat

Voor TCF post het script in het frame een bericht naar het CMP-venster met een object met een eigenschap __tcfapiCall. Daarin zitten vier velden:

De CMP luistert naar deze berichten, voert de opdracht uit en post een object terug met een eigenschap __tcfapiReturn met returnValue, success en dezelfde callId. De aanroeper houdt een map bij van openstaande callbacks, gesorteerd op callId, luistert naar message-gebeurtenissen en stuurt elke terugkeer door naar de juiste callback. GPP volgt hetzelfde patroon met __gppCall en __gppReturn.

Veel integraties schrijven een kleine proxy: een lokale functie met de naam __tcfapi binnen het frame die aanroepen vertaalt naar berichten. Code die voor het bovenste venster is geschreven, werkt dan ongewijzigd binnen het frame.

Event listeners over frames heen

Een via postMessage verstuurde addEventListener-aanroep is geen eenmalig verzoek. De CMP post elke keer dat de toestemmingsstatus verandert een terugkeerbericht, allemaal met dezelfde callId. Je dispatcher moet die callback dus geregistreerd houden in plaats van hem na de eerste respons te verwijderen. Dit vergeten is een klassieke bug: het script in het frame leest de toestemming één keer en merkt een latere intrekking nooit op.

Beveiligingsoverwegingen

Waar het patroon niet bij kan

Sommige advertentieomgevingen isoleren creatives strikter. SafeFrame-containers, gesandboxte iframes zonder de juiste rechten en creatives die in aparte documenten worden gerenderd, kunnen mogelijk de frameboom niet doorlopen of geen berichten ontvangen. In die gevallen moet het toestemmingssignaal meestal expliciet worden doorgegeven, bijvoorbeeld als parameters op het advertentieverzoek of als waarden die de adserver aan de creative meegeeft, zoals de parameters gdpr en gdpr_consent die veel advertentietags ondersteunen.

Debugchecklist

Belangrijkste inzichten

← Blog Alles lezen →