Tutorial15. Okt. 2026 | FlexyConsent

__tcfapi-Event-Listener nutzen: Ein Entwickler-Tutorial für einwilligungsabhängige Skripte

Warum Ihre Skripte zuhören statt pollen sollten

Jedes Skript, das von der Einwilligung abhängt — ein Ad-Tag, ein Analytics-Loader, ein Header-Bidding-Wrapper — muss zwei Dinge wissen: ob die CMP schon eine Entscheidung hat und wie diese lautet. Ein verbreiteter Fehler ist, beim Laden der Seite ein Cookie auszulesen oder die CMP per Timer so lange abzufragen, bis etwas erscheint. Beides scheitert auf vorhersehbare Weise: Das Cookie-Format ist CMP-intern und kann sich ändern, und Polling feuert entweder zu früh oder verschwendet Wartezeit.

Das IAB TCF definiert für genau diese Aufgabe eine standardisierte JavaScript-Schnittstelle: die Funktion __tcfapi. Dieses Tutorial zeigt die Befehle, die Sie wirklich brauchen, die Events, die Sie erhalten, und die Fehler, die in der Produktion am häufigsten auftreten.

Der Stub und die Warteschlange

Eine TCF-CMP soll so früh wie möglich einen kleinen Stub auf der Seite platzieren, noch bevor das vollständige CMP-Skript lädt. Der Stub definiert window.__tcfapi und stellt alle Aufrufe in eine Warteschlange, die vor der Bereitschaft der CMP erfolgen. Sobald die CMP fertig geladen ist, arbeitet sie die Warteschlange ab und beantwortet jeden Aufruf.

Dadurch können andere Skripte __tcfapi gefahrlos sofort aufrufen: Solange der Stub vor ihnen auf der Seite steht, gehen ihre Aufrufe nicht verloren. Wenn ein Skript einen Fehler wirft, weil __tcfapi nicht definiert ist, fehlt der Stub oder er lädt zu spät — korrigieren Sie die Ladereihenfolge, statt Wiederholungsversuche einzubauen.

Die wichtigen Befehle

ping

__tcfapi('ping', 2, callback) liefert den Grundstatus, ohne auf eine Nutzerentscheidung zu warten. Die Antwort enthält cmpLoaded, einen cmpStatus wie stub, loading, loaded oder error sowie einen displayStatus mit visible, hidden oder disabled. Außerdem meldet sie gdprApplies, sobald der Wert bekannt ist. Nutzen Sie sie für die Diagnose und um zu entscheiden, ob das TCF für diesen Besucher überhaupt relevant ist.

addEventListener

__tcfapi('addEventListener', 2, callback) ist der Befehl, den die meisten Integrationen verwenden sollten. Der Callback erhält ein tcData-Objekt und ein Erfolgs-Flag und wird bei jeder Änderung des Einwilligungsstatus erneut aufgerufen. Seit TCF v2.2 ist dies der empfohlene Weg, an Einwilligungsdaten zu kommen; der ältere Befehl getTCData wurde als veraltet eingestuft.

removeEventListener

Jedes tcData-Objekt enthält eine listenerId. Übergeben Sie sie an __tcfapi('removeEventListener', 2, callback, listenerId), wenn Ihr Skript keine Updates mehr braucht — zum Beispiel bei einem einmaligen Loader, der seine Entscheidung bereits getroffen hat.

Den eventStatus lesen

Das Schlüsselfeld in tcData ist eventStatus. Es gibt drei Werte:

Ein typischer Loader wartet entweder auf tcloaded oder auf useractioncomplete und prüft dann die Zwecke und Anbieter, die er braucht. cmpuishown ignoriert er, außer um allenfalls zu protokollieren, dass ein Banner erschienen ist.

Zwecke und Anbieter prüfen

In tcData sind Einwilligung und berechtigtes Interesse als nach ID indizierte Objekte verfügbar:

Prüfen Sie sowohl den Zweck als auch den Anbieter. Eine Zweckeinwilligung ohne Anbietereinwilligung oder umgekehrt genügt den meisten Anbietern nicht, um Daten zu verarbeiten.

Iframes und frameübergreifende Aufrufe

Anzeigen und Widgets laufen oft in Iframes, die das __tcfapi der übergeordneten Seite nicht sehen können. Das TCF löst das mit einem postMessage-Protokoll: Die CMP fügt der obersten Seite einen Frame namens __tcfapiLocator hinzu, und Code in einem Iframe kann ihn finden, eine __tcfapiCall-Nachricht senden und eine __tcfapiReturn-Antwort empfangen. Die meisten Ad-SDKs tun das bereits. Wenn Sie eigenen Iframe-Code schreiben, setzen Sie dasselbe Muster um, statt Cookies über Frames hinweg zu lesen.

Häufige Fehler und wie Sie sie erkennen

  1. Auf cmpuishown reagieren. Skripte, die laden, sobald irgendein Callback feuert, laufen, bevor der Nutzer entschieden hat. Filtern Sie nach eventStatus.
  2. Den Listener zu früh entfernen. Wenn Sie ihn nach dem ersten Callback entfernen, verpassen Sie ein späteres useractioncomplete und laden nie.
  3. Widerrufe ignorieren. Dauerhaft laufende Skripte sollten weiter zuhören und sich beenden oder neu konfigurieren, wenn die Einwilligung widerrufen wird.
  4. gdprApplies ignorieren. Außerhalb von TCF-Regionen können die Zweck-Objekte leer sein; das als „keine Einwilligung“ zu behandeln, kann Umsatz abschalten, den Sie erzielen dürfen.
  5. Das Erfolgs-Flag nicht prüfen. Wenn success false ist, protokollieren Sie das; es deutet meist auf eine fehlerhafte CMP-Einrichtung hin.

Ihre Integration testen

Rufen Sie in der Browserkonsole __tcfapi('ping', 2, console.log) auf, um zu bestätigen, dass die CMP vorhanden ist, registrieren Sie dann einen Listener mit console.log als Callback und klicken Sie sich durch das Banner. Beim ersten Besuch sollten Sie cmpuishown gefolgt von useractioncomplete sehen, nach einem Reload tcloaded. Wiederholen Sie dies mit „Alle akzeptieren“, „Alle ablehnen“ und einer benutzerdefinierten Auswahl und prüfen Sie, ob sich Ihr Skript in jedem Fall korrekt verhält.

Wichtigste Erkenntnisse

← Blog Alle lesen →