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
- 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.
- 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.
- 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:
- command — bijvoorbeeld getTCData, ping of addEventListener;
- parameter — elk argument dat de opdracht nodig heeft, of null;
- version — de API-versie, 2 voor TCF v2;
- callId — een unieke waarde die door de aanroeper wordt gegenereerd.
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
- Valideer de vorm van het bericht. Negeer elk bericht dat niet de verwachte eigenschap bevat en parseer stringpayloads defensief, want sommige implementaties sturen JSON-strings in plaats van objecten.
- Vertrouw niet blindelings. Elke pagina kan berichten naar je frame posten. Behandel antwoorden als toestemmingssignalen om te eerbiedigen, niet als geauthenticeerde gegevens, en laat ze nooit bevoorrechte acties activeren.
- Gebruik waar mogelijk specifieke doel-origins. Als de origin van de CMP bekend is, post dan naar die origin in plaats van naar elke origin.
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
- Bevestig in DevTools van het bovenste venster dat de locatorframes in het Elements-paneel bestaan.
- Schakel de consolecontext om naar het iframe en controleer of de locator van daaruit bereikbaar is.
- Log inkomende message-gebeurtenissen in beide vensters om te bevestigen dat aanroepen en terugkeerwaarden stromen.
- Wijzig de toestemming in de banner en verifieer dat listeners in frames een update ontvangen.
- Test met een laat geladen CMP, om te controleren of code in frames het opnieuw probeert of wacht in plaats van meteen op te geven.
Belangrijkste inzichten
- Cross-origin-frames bereiken de CMP via de frames __tcfapiLocator en __gppLocator.
- Aanroepen en terugkeerwaarden gebruiken postMessage met __tcfapiCall/__tcfapiReturn of de GPP-equivalenten, gekoppeld via callId.
- Houd listener-callbacks geregistreerd zodat latere toestemmingswijzigingen aankomen.
- Valideer elk bericht en behandel het niet als vertrouwde invoer.
- Waar frames volledig geïsoleerd zijn, geef toestemming expliciet door op het advertentieverzoek.