TikTok Pixel & Events API (Conversion API)

Installationsanleitung, Dokumentation und FAQs zum Shopware Plugin

TikTok Pixel & Events API (Conversion API)

Mit diesem Plugin binden Sie das TikTok Pixel sauber in Ihren Shopware-Shop ein und übertragen alle relevanten Shop-Ereignisse zusätzlich serverseitig über die TikTok Events API (Conversion API). So messen Sie Ihre TikTok-Kampagnen präzise – datenschutzkonform und erst nach Cookie-Einwilligung.

  1. Clientseitiges TikTok Pixel und serverseitige Events API (Conversion API)
  2. Deduplizierung von Browser- und Server-Events über eine gemeinsame Event-ID
  3. Standard-Events: ViewContent, AddToCart, InitiateCheckout, AddPaymentInfo, CompletePayment und Search
  4. Enhanced Matching mit serverseitig per SHA-256 gehashter E-Mail und Telefonnummer
  5. Eigene Pixel-ID und Events-API-Token je Verkaufskanal sowie gezielter Ausschluss einzelner Kundengruppen

Voraussetzungen

  • Ein aktives TikTok-for-Business-Konto mit eingerichtetem Pixel und Zugriff auf den Events Manager
  • Für die serverseitige Events API zusätzlich ein Events-API-Access-Token aus dem TikTok Events Manager
  • Shopware 6.7
  • Ein aktiver Cookie-Consent-Manager (Shopware-Standard oder ein unterstütztes externes Tool), damit das Pixel rechtskonform geladen wird

Kompatibilität

Das Plugin ist mit Shopware 6.7 kompatibel. Das clientseitige Pixel wird über den offiziellen TikTok-Analytics-Code geladen, die serverseitige Übermittlung erfolgt direkt von Ihrem Shop an die TikTok Events API. Zusätzliche Drittanbieter-Plugins sind nicht erforderlich.

Installation

  1. Plugin im Shopware Store erwerben und in Ihrem Shop installieren.
  2. Plugin unter Erweiterungen aktivieren.
  3. Konfiguration öffnen und die TikTok Pixel-ID (sowie optional das Events-API-Token) hinterlegen (siehe „Einrichtung“).
  4. Storefront-Cache leeren bzw. die Seite neu laden, damit das Pixel ausgespielt wird.

Einrichtung

Öffnen Sie die Plugin-Konfiguration unter Erweiterungen › Meine Erweiterungen beim Eintrag „TikTok Pixel & Events API (Conversion API)“ über das Drei-Punkte-Menü › Konfiguration. Wählen Sie oben den gewünschten Verkaufskanal aus und nehmen Sie die folgenden Einstellungen vor:

  • Aktiv: Schaltet das Tracking für den gewählten Verkaufskanal ein.
  • TikTok Pixel-ID: Ihre Pixel-ID aus dem TikTok Events Manager (z. B. C1A2B3…).
  • Serverseitiges Tracking über die TikTok Events API: Aktiviert die zusätzliche Server-zu-Server-Übermittlung.
  • Events-API-Access-Token: Das im TikTok Events Manager erzeugte Token für die Events API.
  • Währung überschreiben: Optional. Leer lassen, um die Währung des Verkaufskanals zu verwenden, oder eine feste Währung (z. B. EUR) vorgeben.
Plugin-Konfiguration des TikTok Pixel & Events API in der Shopware-Administration
Plugin-Konfiguration: Pixel-ID, Events-API-Token, Enhanced Matching und Tracking-Optionen

1 · Erfasste Ereignisse

Ist das Tracking aktiv und die Einwilligung erteilt, erfasst das Plugin automatisch die wichtigsten Ereignisse im Kaufprozess und meldet sie an TikTok:

  • ViewContent: Produktansicht
  • AddToCart: Artikel in den Warenkorb gelegt
  • InitiateCheckout: Beginn des Bestellvorgangs
  • AddPaymentInfo: Zahlungsdaten hinterlegt
  • CompletePayment: abgeschlossene Bestellung mit Umsatz und Währung
  • Search: Suche mit dem eingegebenen Suchbegriff

Das eCommerce-Tracking lässt sich in der Konfiguration separat aktivieren oder deaktivieren.

2 · Server-Events-API & Enhanced Matching

Zusätzlich zum clientseitigen Pixel überträgt das Plugin dieselben Ereignisse serverseitig über die TikTok Events API (Conversion API) direkt von Ihrem Shop an TikTok. Browser- und Server-Ereignis teilen sich eine gemeinsame Event-ID, sodass TikTok sie zuverlässig dedupliziert und jedes Ereignis nur einmal zählt.

Das serverseitige Tracking arbeitet unabhängig von Ad-Blockern und Browser-Einschränkungen und sorgt so für eine deutlich stabilere Conversion-Messung.

Mit aktiviertem Enhanced Matching übergibt das Plugin zusätzlich gehashte Kundendaten (E-Mail und Telefonnummer) an die Events API. Das Hashing erfolgt serverseitig per SHA-256 – Klartextdaten verlassen Ihren Shop nicht. So ordnet TikTok Conversions zuverlässiger den richtigen Nutzern zu.

  • Serverseitiges Tracking über die Events API: aktiviert die Server-zu-Server-Übermittlung.
  • Enhanced Matching: sendet gehashte E-Mail und Telefonnummer.
  • Events API asynchron versenden: verarbeitet die Aufrufe über die Shopware Message Queue, ohne die Storefront zu verlangsamen.
  • Protokollierung: schreibt die Events-API-Aufrufe in die Shopware-Logs zur Diagnose.
  • Test-Event-Code: nur zum Testen. Mit hinterlegtem Code erscheinen die Ereignisse im TikTok Events Manager unter „Test Events“. Im Produktivbetrieb leer lassen.

3 · Cookie-Einwilligung & Datenschutz

Das TikTok Pixel wird erst geladen, wenn der Besucher der Kategorie „Marketing“ zugestimmt hat. Wird die Einwilligung widerrufen, stoppt das Tracking.

Unterstützt werden der Shopware Cookie-Consent-Manager sowie sieben externe Consent-Tools:

  • Cookie Bot
  • CookieFirst
  • UserCentrics
  • ACRIS EU Cookie Richtlinie Pro
  • CCM19
  • CMP
  • CookieYes

Für individuelle Setups können Sie im Feld „Expertenmodus für den ausgewählten Consent-Manager“ das Daten-Attribut frei festlegen, mit dem das TikTok-Pixel zurückgehalten wird (z. B. das Marketing-Attribut Ihres CMP). Für CMP (consentmanager.net) tragen Sie hier Ihre TikTok-Vendor-ID ein.

Hinweis zum Datenschutz: TikTok wird von ByteDance betrieben; bei der Nutzung können Daten auch außerhalb der EU verarbeitet werden. Informieren Sie Ihre Besucher entsprechend in Ihrer Datenschutzerklärung und holen Sie eine gültige Einwilligung ein.

Cookie-Voreinstellungen in der Storefront mit dem TikTok Pixel in der Marketing-Kategorie
Cookie-Dialog: Das TikTok Pixel erscheint in der Kategorie „Marketing“.

4 · Mehrere Verkaufskanäle & weitere Optionen

  • Mehrere Verkaufskanäle: Wählen Sie oben in der Konfiguration den jeweiligen Verkaufskanal und hinterlegen Sie pro Kanal eine eigene Pixel-ID und ein eigenes Events-API-Token.
  • Eigene Ereignisse: Im Feld „Eigene Ereignisse“ definieren Sie pro Zeile zusätzliche Events im Format „route_name = EventName“. Lassen Sie die Route weg (nur „EventName“), um das Ereignis auf jeder Seite auszulösen. Zeilen, die mit # beginnen, werden ignoriert.
  • Brutto/Netto: Legen Sie fest, ob Umsätze brutto oder netto übergeben werden.
  • Bestellwert: Übermitteln Sie den Bestellwert inklusive oder exklusive Versandkosten.
  • Kundengruppen ausschließen: Unter „Tracking für folgende Kundengruppen deaktivieren“ nehmen Sie einzelne Kundengruppen (z. B. Händler oder interne Gruppen) vom Tracking aus.
  • 24 Sprachen: Administration und Storefront-Texte stehen in 24 Sprachen zur Verfügung.

FAQs

Beides finden Sie im TikTok Events Manager bei Ihrem Pixel. Die Pixel-ID wird beim Anlegen des Pixels erzeugt; das Events-API-Access-Token erstellen Sie in den Einstellungen des Pixels im Bereich „Events API“. Tragen Sie beide Werte in der Plugin-Konfiguration ein.

Das TikTok Pixel wird erst nach Zustimmung zur Marketing-Kategorie im Cookie-Dialog geladen. Prüfen Sie außerdem, ob das Plugin für den richtigen Verkaufskanal aktiv ist und eine gültige Pixel-ID hinterlegt wurde.

Nein. Das clientseitige Pixel funktioniert eigenständig. Die Events API ist optional, verbessert aber die Datenqualität deutlich, da sie unabhängig von Ad-Blockern und Browser-Einschränkungen arbeitet. Für sie benötigen Sie ein Events-API-Access-Token.

Mit hinterlegtem Test-Event-Code erscheinen Ihre Ereignisse im TikTok Events Manager unter „Test Events“, sodass Sie das Setup prüfen können. Für den Produktivbetrieb lassen Sie das Feld leer.

Unter „Tracking für folgende Kundengruppen deaktivieren“ wählen Sie die betroffenen Kundengruppen aus. Für diese werden weder Pixel- noch Events-API-Ereignisse ausgespielt.

Support

Bei Fragen oder Problemen stehen wir zur Verfügung: