{"id":10129,"date":"2026-09-20T13:14:00","date_gmt":"2026-09-20T11:14:00","guid":{"rendered":"https:\/\/www.lukaswojcik.com\/blog\/?p=10129"},"modified":"2026-09-09T13:23:07","modified_gmt":"2026-09-09T11:23:07","slug":"tutorial-die-tiktok-events-api-fur-onlineshops-implementieren","status":"publish","type":"post","link":"https:\/\/www.lukaswojcik.com\/blog\/de\/digital-marketing-de\/tutorials-de-digital-marketing-de\/tutorial-die-tiktok-events-api-fur-onlineshops-implementieren\/","title":{"rendered":"Tutorial: Die TikTok Events API f\u00fcr Onlineshops implementieren"},"content":{"rendered":"
Ein TikTok-Pixel allein meldet weniger K\u00e4ufe, als ein Shop tats\u00e4chlich abwickelt. Blocker, der Tracking-Schutz im Browser und Besucher, die den Tab schlie\u00dfen, bevor die Best\u00e4tigungsseite fertig gerendert ist, entfernen Events, die stattgefunden haben. Dieselben K\u00e4ufe ein zweites Mal vom Server zu senden schlie\u00dft diese L\u00fccke \u2013 und erzeugt ein neues Problem, denn TikTok erh\u00e4lt nun zwei Meldungen \u00fcber einen Kauf.<\/p>\n
Aufgel\u00f6st wird das \u00fcber eine gemeinsame event_id<\/code>: ein Wert, je Kauf einmal erzeugt und unver\u00e4ndert auf beiden Wegen gesendet. Die folgende Anleitung baut diese Architektur vollst\u00e4ndig f\u00fcr einen Shop auf \u2013 das Browser-Event, die Kennungen, die der Server von sich aus nicht sieht, die Server-Anfrage und die Pr\u00fcfung, ob die Deduplizierung tats\u00e4chlich greift.<\/p>\n\nDas Pixel liefert den Browser-Kontext, der Server die Verlässlichkeit – die gemeinsame event_id hält beides bei einer Conversion.<\/figcaption><\/figure>\n
Schritt 1: Die Event-ID einmal erzeugen<\/h2>\n
Die event_id<\/code> muss an einer Stelle erzeugt und wiederverwendet werden \u2013 sie unabh\u00e4ngig auf beiden Seiten zu erzeugen scheidet damit aus, denn zwei Zufallswerte beschreiben aus Sicht von TikTok zwei getrennte Conversions. F\u00fcr einen Shop ist die Bestellnummer die naheliegende Quelle: Sie existiert im Moment des Kaufs bereits, ist stabil und steht sowohl der Best\u00e4tigungsseite als auch dem Backend zur Verf\u00fcgung.<\/p>\n
Ein Pr\u00e4fix h\u00e4lt Eventtypen auseinander, denn eine einzelne Bestellung kann mehr als ein getracktes Event erzeugen. Eine event_id<\/code> purchase-10432<\/code> f\u00fcr den Kauf und checkout-10432<\/code> f\u00fcr den Checkout-Start h\u00e4lt jedes Paar bei seinem eigenen Gegenst\u00fcck. Als Nebeneffekt erzeugt ein Besucher, der die Best\u00e4tigungsseite neu l\u00e4dt, dieselbe event_id<\/code> erneut und wird dedupliziert statt doppelt gez\u00e4hlt.<\/p>\n
Schritt 2: Das Browser-Event<\/h2>\n
Im TikTok-Pixel reist die Kennung im dritten Argument von ttq.track<\/code>, getrennt von den Event-Eigenschaften:<\/p>\n
Auch der Eventname muss auf beiden Seiten \u00fcbereinstimmen. TikTok paart die beiden Meldungen \u00fcber die Kombination aus Eventname und event_id<\/code>; CompletePayment<\/code> im Browser und Purchase<\/code> auf dem Server sind also zwei verschiedene Events, die nie gegeneinander deduplizieren \u2013 gleich wie sorgf\u00e4ltig die Kennung abgeglichen wird.<\/p>\n
Schritt 3: Die Kennungen erfassen, die der Server nicht sieht<\/h2>\n
Zwei Werte existieren nur im Browser. ttclid<\/code> kommt als URL-Parameter an, wenn ein Besucher \u00fcber eine TikTok-Anzeige landet, und _ttp<\/code> ist das First-Party-Cookie, das das Pixel setzt. Beide verbessern die Zuordnung der Server-Anfrage, und beide m\u00fcssen beim Landen gesichert werden \u2013 die Best\u00e4tigungsseite liegt meist mehrere Navigationen sp\u00e4ter, und der URL-Parameter ist dann l\u00e4ngst weg:<\/p>\n
\/\/ Beim Landen: Klick-ID fuer den restlichen Besuch sichern\nconst ttclid = new URLSearchParams(window.location.search).get('ttclid');\nif (ttclid) {\n document.cookie = 'shop_ttclid=' + encodeURIComponent(ttclid) +\n ';max-age=2592000;path=\/;secure;samesite=Lax';\n}<\/code><\/pre>\n
Im Checkout werden beide Werte aus den Cookies gelesen und am Bestelldatensatz gespeichert, damit das Backend sie beim Bau des Server-Events zur Hand hat. IP-Adresse und User Agent des Besuchers stammen aus der urspr\u00fcnglichen HTTP-Anfrage und geh\u00f6ren in denselben Datensatz \u2013 eine sp\u00e4ter vom Server gesendete Anfrage hat weder das eine noch das andere von sich aus.<\/p>\n
Schritt 4: Die Server-Anfrage<\/h2>\n
Die Events API nimmt einen POST an den event\/track\/<\/code>-Endpunkt der TikTok Business API entgegen, authentifiziert \u00fcber ein Access Token aus dem TikTok Events Manager und \u00fcber event_source_id<\/code> an ein Pixel adressiert. Identifizierende Felder werden normalisiert und dann per SHA-256 gehasht; nichts Identifizierendes verl\u00e4sst den Server im Klartext:<\/p>\n
Die Normalisierung vor dem Hashen entscheidet, ob die Kennungen \u00fcberhaupt etwas treffen: E-Mail getrimmt und kleingeschrieben, Telefonnummer auf Ziffern im internationalen E.164-Format reduziert. Derselbe Wert, einmal aus Anna@Example.com <\/code> und einmal aus anna@example.com<\/code> gehasht, ergibt zwei unabh\u00e4ngige Digests, von denen nur einer passen kann. event_time<\/code> ist ein Unix-Zeitstempel in Sekunden, und die Anfrage geh\u00f6rt unmittelbar hinter die Bestellbest\u00e4tigung statt in einen n\u00e4chtlichen Stapel. TikTok weist zu sp\u00e4t eintreffende Events ab, und ein Batch-Job merkt das erst, wenn das Zeitfenster bereits zu ist.<\/p>\n
Schritt 5: Pr\u00fcfen, ob die Deduplizierung greift<\/h2>\n
Das Feld test_event_code<\/code> aus dem Reiter f\u00fcr Testereignisse im Events Manager leitet eine Anfrage in die Testansicht, ohne das Reporting zu ber\u00fchren \u2013 genug, um zu best\u00e4tigen, dass die Nutzlast angenommen und die gehashten Felder erkannt werden.<\/p>\n
Die Deduplizierung selbst zeigt sich erst in Echtdaten. Im Events Manager weist ein Event, das beide Kan\u00e4le erh\u00e4lt, seine Browser- und Serverzahlen getrennt aus; die Differenz zwischen deren Summe und dem deduplizierten Gesamtwert ist der Beleg, dass die Paarung funktioniert. Ein Gesamtwert, der genau der Summe beider Kan\u00e4le entspricht, bedeutet, dass nichts zusammengef\u00fchrt wird \u2013 meist ein abweichender Eventname oder eine je Seite getrennt erzeugte event_id<\/code>. Der Abgleich der deduplizierten Zahl gegen die tats\u00e4chlichen Bestellungen im Shop-Backend ist die Pr\u00fcfung, auf die es ankommt; TikToks eigene Zahlen k\u00f6nnen keinen Kauf zeigen, den kein Kanal gemeldet hat.<\/p>\n
Innerhalb der Leitplanken bleiben<\/h2>\n
Beide Kan\u00e4le geh\u00f6ren hinter dasselbe Werbe-Consent-Signal. Eine serverseitige Anfrage ist nicht deshalb von der Einwilligung ausgenommen, weil sie aus einem Backend stammt: Sie tr\u00e4gt dieselben Kundendaten, und die Rechtsgrundlage daf\u00fcr ist die im Browser eingeholte \u2013 der Consent-Status muss also am Auftrag gespeichert und vor dem Bau der Anfrage gepr\u00fcft werden. Rohe E-Mail-Adressen und Telefonnummern existieren nur so lange, bis sie normalisiert und gehasht sind, und das Access Token geh\u00f6rt in einen Secrets-Speicher statt in den Anwendungscode, denn es berechtigt zum Schreiben von Conversions in das Werbekonto.<\/p>\n
![\"Zweispaltiger](\"https:\/\/www.lukaswojcik.com\/blog\/wp-content\/uploads\/diagrams\/tiktok-events-api-de.png\")