Einwilligung in Cross-Origin-Iframes: Das Muster __tcfapiLocator und __gppLocator

Das Problem: Die Einwilligung lebt im obersten Fenster

Eine CMP läuft auf Ihrer Seite, im Fenster der obersten Ebene. Ein Großteil Ihrer Werbung nicht. Display-Creatives, Rich Media, Renderer des Header Biddings und viele Drittanbieter-Widgets laufen in Iframes, oft auf einer anderen Origin. Code in einem Cross-Origin-Iframe kann keine Funktion der übergeordneten Seite direkt aufrufen und daher nicht einfach __tcfapi oder __gpp aufrufen und die Entscheidung des Besuchers lesen.

Die IAB-Frameworks lösen das mit einer kleinen, klar definierten Nachrichtenkonvention. Wenn Sie Werbeprodukte, Einbettungen oder Messskripte bauen, die in Frames laufen, oder Ad-Stacks debuggen, die das tun, lohnt es sich zu wissen, wie genau sie funktioniert.

Der Locator-Frame

Neben der JavaScript-API fügt eine TCF-CMP der Seite der obersten Ebene einen leeren, unsichtbaren Iframe namens __tcfapiLocator hinzu. Eine GPP-CMP tut dasselbe mit einem Frame namens __gppLocator. Die Frames haben keinen Inhalt. Ihre einzige Aufgabe ist es, auffindbar zu sein: Jedes Skript in jedem verschachtelten Frame kann die Fensterhierarchie nach oben wandern und auf jeder Ebene prüfen, ob ein Frame mit diesem Namen existiert.

Weil Frame-Namen über window.frames origin-übergreifend sichtbar sind, kann ein Skript in einem tief verschachtelten Cross-Origin-Iframe das Fenster finden, das die CMP beherbergt, ohne Zugriff auf irgendetwas anderes auf dieser Seite zu haben.

Wie ein Skript im Frame die CMP findet

  1. Beginnen Sie mit dem aktuellen Fenster. Existiert __tcfapi lokal, verwenden Sie es direkt — das Skript befindet sich nicht in einem Frame, oder der Frame teilt sich die CMP.
  2. Andernfalls laufen Sie nach oben: Prüfen Sie, ob das aktuelle Fenster einen Frame namens __tcfapiLocator enthält; wenn nicht, gehen Sie zu window.parent und prüfen erneut, bis das oberste Fenster erreicht ist.
  3. Ist der Locator gefunden, ist das Fenster, das ihn enthält, das Fenster der CMP. Die Kommunikation läuft nun über postMessage.

Kapseln Sie jeden Zugriff in try/catch, da manche Browser oder Sandbox-Einstellungen bei Cross-Origin-Zugriffen auf Eigenschaften Fehler auslösen, und beenden Sie die Schleife, wenn window.parent dem aktuellen Fenster entspricht.

Das Nachrichtenformat

Bei TCF sendet das Skript im Frame eine Nachricht an das CMP-Fenster, die ein Objekt mit einer Eigenschaft __tcfapiCall enthält. Darin liegen vier Felder:

Die CMP lauscht auf diese Nachrichten, führt den Befehl aus und sendet ein Objekt mit einer Eigenschaft __tcfapiReturn zurück, das returnValue, success und dieselbe callId enthält. Der Aufrufer führt eine Map ausstehender Callbacks, geordnet nach callId, lauscht auf message-Ereignisse und leitet jede Rückgabe an den richtigen Callback weiter. GPP folgt demselben Muster mit __gppCall und __gppReturn.

Viele Integrationen schreiben einen kleinen Proxy: eine lokale Funktion namens __tcfapi im Frame, die Aufrufe in Nachrichten übersetzt. Für das oberste Fenster geschriebener Code funktioniert dann unverändert im Frame.

Event-Listener über Frames hinweg

Ein per postMessage gesendeter Aufruf von addEventListener ist keine einmalige Anfrage. Die CMP sendet bei jeder Änderung des Einwilligungsstatus eine Rückgabenachricht, alle mit derselben callId. Ihr Dispatcher muss diesen Callback daher registriert lassen, statt ihn nach der ersten Antwort zu löschen. Das zu vergessen ist ein klassischer Fehler: Das Skript im Frame liest die Einwilligung einmal und bemerkt einen späteren Widerruf nie.

Sicherheitsaspekte

Wo das Muster nicht hinreicht

Manche Werbeumgebungen isolieren Creatives strenger. SafeFrame-Container, Sandbox-Iframes ohne die richtigen Berechtigungen und in separaten Dokumenten gerenderte Creatives können den Frame-Baum womöglich nicht durchlaufen oder keine Nachrichten empfangen. In solchen Fällen muss das Einwilligungssignal meist ausdrücklich übergeben werden, zum Beispiel als Parameter der Anzeigenanfrage oder als Werte, die der Ad-Server dem Creative übergibt, etwa die Parameter gdpr und gdpr_consent, die viele Ad-Tags unterstützen.

Debugging-Checkliste

Wichtigste Erkenntnisse

← Blog Alle lesen →