Tutorial: Die TikTok Events API für Onlineshops implementieren

Ein Browser-Pixel kann Käufe verpassen, etwa durch Blocker oder eine vorzeitig geschlossene Bestätigungsseite. Die TikTok Events API ergänzt einen zweiten Meldeweg aus dem Shop-Backend. Das kann die technische Abdeckung verbessern, garantiert aber weder vollständige Erfassung noch die Zuordnung jedes Kaufs zu einer Anzeige.

Ein Pixel ist Messcode im Browser. Das Backend ist die auf dem Shop-Server laufende Software. Eine API ist eine Schnittstelle zum Datenaustausch zwischen Programmen; ein Access Token ist der dafür verwendete Zugangsnachweis. Deduplizierung erkennt wiederholte Meldungen desselben Ereignisses. Attribution ordnet einen Kauf nach festgelegten Regeln einer Anzeige zu.

Die folgende Anleitung verbindet beide Wege über dieselbe Ereigniskennung. Voraussetzung sind ein TikTok-Pixel, ein nur serverseitig gespeichertes Access Token, eine angebundene Einwilligungsverwaltung und ein verlässliches Kaufereignis im Backend. Die Beispiele zeigen die Datenübergabe; Shop-Anbindung, Versandwarteschlange und Fehlerbehandlung bleiben eigene Implementierungsschritte.

Schritt 1: Einen bestätigten Kauf eindeutig kennzeichnen

Die event_id entsteht einmal im Backend und bleibt für Browsermeldung, Servermeldung und Wiederholungsversuche gleich. Beispielsweise bezeichnet purchase-10432 genau einen bestätigten Kauf. Eine Bestellnummer darf dafür keine personenbezogenen Angaben enthalten und muss innerhalb der Datenquelle eindeutig sein. Für wiederkehrende Zahlungen ist eine eigene Kennung je Zahlung erforderlich.

TikTok dedupliziert anhand von Pixel-Code, Ereignisname und event_id innerhalb eines Zeitfensters von 48 Stunden. Ein Neuladen nach Ablauf dieses Fensters ist damit nicht dauerhaft abgesichert. Der Shop muss wiederholte Kaufmeldungen zusätzlich begrenzen, etwa über einen Versandstatus je Ereignis. Der ursprüngliche Kaufzeitpunkt bleibt auch bei einer erneuten Zustellung erhalten.

Schritt 2: Dasselbe Kaufobjekt an das Pixel übergeben

Das Backend stellt der Bestätigungsseite ausgewählte Felder des bestätigten Kaufs in einem Format, das sich sicher in die Seite einbetten lässt, bereit: event_id, contents, value und currency. Preis, Währung und Warenkorb stammen aus diesem Datensatz, nicht aus frei veränderbaren URL-Parametern. Das folgende Beispiel setzt ein bereits initialisiertes, durch die Einwilligungsverwaltung gesteuertes Pixel voraus:

function sendTikTokPurchase(purchase, advertisingConsent) {
  if (advertisingConsent !== true) return false;
  if (!purchase.event_id || !window.ttq) return false;
  window.ttq.track('Purchase', {
    content_type: 'product',
    contents: purchase.contents,
    value: purchase.value,
    currency: purchase.currency
  }, { event_id: purchase.event_id });
  return true;
}

Der Aufruf erfolgt erst nach bestätigtem Kauf und aktuell erteilter Werbe-Einwilligung. true als Rückgabewert bedeutet lediglich, dass ttq.track aufgerufen wurde; eine Zustellbestätigung ist damit nicht verbunden. Die Initialisierung des Pixels und andere automatische Events benötigen dieselbe Einwilligungssteuerung.

Neue Implementierungen verwenden auf beiden Wegen Purchase. Seit Mai 2025 ordnet TikTok den früheren Namen CompletePayment automatisch Purchase zu. Der alte Name bleibt unterstützt. Unterschiedliche Schreibweisen ohne dokumentierte Zuordnung sind weiterhin eine Fehlerquelle.

Schritt 3: Klick-ID und Browser-Kontext mit Einwilligung sichern

ttclid kann in der URL einer Anzeigen-Landingpage stehen; _ttp ist ein Cookie des Pixels. Diese Werte sind nicht ausschließlich im Browser sichtbar: Der Shop-Server kann URL-Parameter und mitgesendete Cookies ebenfalls lesen. Ein Cookie kann beim ersten Seitenaufruf allerdings noch fehlen. Nicht vorhandene Kennungen bleiben ausgelassen; erfundene Ersatzwerte verschlechtern die Datenqualität.

Eine einfache clientseitige Variante speichert eine vorhandene Klick-ID erst nach Freigabe. Die Funktion wird von der Einwilligungsverwaltung sowohl bei der ersten Entscheidung als auch bei späteren Änderungen aufgerufen:

function updateTikTokClickCookie(advertisingConsent) {
  const attributes = ';path=/;Secure;SameSite=Lax';
  if (advertisingConsent !== true) {
    document.cookie = 'shop_ttclid=;max-age=0' + attributes;
    return;
  }
  const clickId = new URLSearchParams(location.search).get('ttclid');
  // Local size limit, not a TikTok identifier-format specification.
  if (!clickId || clickId.length > 1024) return;
  document.cookie = 'shop_ttclid=' + encodeURIComponent(clickId) +
    ';max-age=2592000' + attributes;
}

Die 30 Tage sind eine beispielhafte lokale Aufbewahrungsentscheidung, keine TikTok-Vorgabe und keine Zusicherung der Browserlaufzeit. Ein späterer Seitenaufruf ohne ttclid verlängert das Cookie nicht. Bei Ablehnung oder Widerruf wird das hier erzeugte Cookie gelöscht. Bereits serverseitig gespeicherte Kennungen und geplante Events benötigen eine entsprechende Widerrufsbehandlung; andere Cookie-Pfade oder Domains werden von dieser Löschung nicht erfasst.

Beim Abschluss der Bestellung kann der Shop vorhandene Kennungen dem Kauf zuordnen. Für ttp wird der Wert von _ttp verwendet. IP-Adresse und User Agent (die vom Browser gemeldete Softwarebeschreibung) müssen aus dem ursprünglichen Besuch stammen, nicht aus dem späteren API-Aufruf. Ein Reverse Proxy nimmt Anfragen vor dem Shop-Server entgegen und leitet diese weiter. Der Shop darf weitergereichte IP-Adressen nur von korrekt eingerichteten, vertrauenswürdigen Zwischenservern übernehmen.

Schritt 4: Daten für den Serverversand vorbereiten

Das Ziel ist POST https://business-api.tiktok.com/open_api/v1.3/event/track/ mit den Headern Access-Token und Content-Type: application/json. event_source_id enthält denselben Pixel-Code wie die Browserintegration. Der folgende Python-Baustein erzeugt nur die Nutzlast und führt keinen Netzwerkaufruf aus:

import hashlib
import re

def sha256(value):
    return hashlib.sha256(value.encode('utf-8')).hexdigest()

def build_payload(pixel_code, order, advertising_consent,
                  email, phone_e164=None):
    if advertising_consent is not True:
        return None
    email = email.strip().lower()
    if not email:
        raise ValueError('Missing email for this example')
    user = {'email': sha256(email)}
    if phone_e164 is not None:
        # Input already parsed and validated for its country.
        if not re.fullmatch(r'\+[1-9][0-9]{1,14}', phone_e164):
            raise ValueError('Expected international phone number with +')
        user['phone'] = sha256(phone_e164)
    return {
        'event_source': 'web',
        'event_source_id': pixel_code,
        'data': [{
            'event': 'Purchase',
            'event_time': order['confirmed_at_unix'],
            'event_id': order['event_id'],
            'user': user,
            'properties': {
                'content_type': 'product',
                'contents': order['contents'],
                'currency': order['currency'],
                'value': order['value']
            },
            'page': {'url': order['confirmation_url']}
        }]
    }

order bezeichnet einen bereits validierten Backend-Datensatz: bestätigter Kauf, stabil gespeicherte Ereigniskennung, Kaufzeitpunkt als ganze Sekunden seit dem 1. Januar 1970 UTC (Unix-Zeit), passender Währungscode wie EUR, numerischer Wert und Produktliste. Die Bestätigungs-URL muss zur Shop-Domain gehören und darf keine E-Mail-Adresse, Zugangstoken oder andere vertrauliche Parameter enthalten. Die Freigabe stammt aus dem vertrauenswürdigen Consent-Datensatz einschließlich bekannter Widerrufe; ein Browserfeld allein genügt dafür nicht.

Das Beispiel entfernt Leerraum am Anfang und Ende der E-Mail-Adresse und schreibt Buchstaben klein. SHA-256 berechnet anschließend aus diesem Text einen Hashwert fester Länge. Eine optionale Telefonnummer muss bereits fachgerecht normalisiert vorliegen, beispielsweise +12133734253; das Pluszeichen bleibt beim Hashen erhalten. Die Formatregel (regulärer Ausdruck, kurz Regex) prüft lediglich die Grundform, nicht die tatsächliche Gültigkeit einer Telefonnummer. Vor diesem Baustein muss die Nummer anhand der Regeln des zugehörigen Landes eingelesen und geprüft werden. Fehlende Telefonnummern werden ausgelassen. E-Mail ist nur für dieses vereinfachte Beispiel Pflicht, nicht die einzige von TikTok unterstützte Matching-Möglichkeit.

Hashing macht Daten nicht anonym. Zusätzliche unterstützte Felder benötigen eigene Regeln: external_id wird gehasht, während ttclid, ttp, IP-Adresse und User Agent ungehasht übertragen werden. Rohdaten und Hashes gehören nicht in allgemeine Debug-Logs. Für die Auftragsabwicklung erforderliche Kontaktdaten unterliegen unabhängig davon dem jeweiligen Aufbewahrungskonzept.

Der Versand erfolgt möglichst zeitnah nach dem bestätigten Kauf. Eine Warteschlange hält ursprüngliche ID und Ereigniszeit unverändert, prüft Einwilligung vor der Zustellung erneut und begrenzt Wiederholungen. Der HTTP-Status bezeichnet den Antwortstatus der Webanfrage. JSON enthält die strukturierten Ergebnisdaten. Beide Angaben müssen gemeinsam ausgewertet werden: code: 0 bestätigt API-Erfolg, aber weder Personen-Matching noch Anzeigenattribution. Ein Timeout bedeutet, dass innerhalb der Wartefrist keine Antwort eintraf. Das kann auch nach erfolgreicher Annahme auftreten und braucht den Status „Ergebnis unbekannt“ statt einer neuen Ereigniskennung.

Schritt 5: Zustellung, doppelte Meldungen und Anzeigenzuordnung getrennt prüfen

Test Events und der dort bereitgestellte test_event_code dienen zur Prüfung der gewählten Integration. Testdaten werden vom Produktionsbetrieb getrennt; vor dem echten Versand muss die Testkonfiguration entfernt sein. Sichtbare Hash-Felder belegen keine erfolgreiche Zuordnung zu einer Person. Eine kontrollierte Testbestellung prüft beide Kanäle, denselben Pixel-Code, dieselbe Ereigniskennung und die übereinstimmenden Kaufwerte.

Für die laufende Kontrolle sind die Deduplizierungsdetails und Diagnosen im Events Manager entscheidend. Browser-, Server- und gemeinsame Events dürfen nicht ohne Prüfung der jeweiligen Metrikdefinition addiert werden. Gleich große Summen allein beweisen keinen Fehler: Ohne Überschneidung gibt es auch keine doppelten Meldungen. Außerdem können Anzeigeverzögerungen, Zeitzonen und Filter den Vergleich verändern.

Ein Abgleich mit dem Shop betrachtet dieselben Kaufdefinitionen und Zeiträume sowie die zur Übermittlung freigegebenen Käufe. „Total Events“ umfasst Ereignisse mit und ohne Anzeigenzuordnung. Die im Ads Manager gezählten Anzeigenkäufe hängen zusätzlich vom Personenabgleich und vom Attributionsfenster ab: dem zulässigen Zeitraum zwischen Anzeigenkontakt und Kauf. Ein angenommenes Event ist daher kein garantierter Anzeigenkauf.