Conversion-Tracking für Lightspeed eCom-Webshops

Conversion-Tracking für Lightspeed bedeutet, jede bezahlte Bestellung in deinem Lightspeed-eCom-Webshop an Werbeplattformen wie Meta und TikTok zu melden, damit diese die richtigen Anzeigen belohnen und deine Kampagnen optimieren können. Der zuverlässige Weg ist, jeden Kauf auf dem Server aus den Bestelldaten von Lightspeed zu senden und der Dankeseite ein kurzes Snippet hinzuzufügen, das die Bestellung mit dem Anzeigenklick verknüpft.

Dieser Leitfaden behandelt, für welches Lightspeed-Produkt er gilt, wie Bestellungen zu ROASaurus gelangen, was aus jeder Bestellung gelesen wird, wie Käufe zu Meta und TikTok gelangen, die Einrichtung, das Testen und die Grenzen, die du kennen solltest.

Welches Lightspeed-Produkt behandelt dieser Leitfaden?

Lightspeed verkauft mehr als ein E-Commerce-Produkt, prüfe daher zuerst deines. ROASaurus verbindet sich mit Lightspeed eCom (C-Series), der Webshop-Plattform, in deren Backoffice es Settings › Website Settings › Web Extras gibt. Die API dieser Plattform läuft auf zwei Clustern:

Jede API-Adresse enthält außerdem einen zweistelligen Sprachcode, zum Beispiel /nl/ oder /en/. ROASaurus fragt ihn als Shop-Sprache ab und verwendet nl, wenn du das Feld leer lässt.

Lightspeed bietet außerdem eCom (E-Series) an. Lightspeed beschreibt den Wechsel zu E-Series als Upgrade auf ein eigenes Produkt, das derzeit bestimmten Händlern in Nordamerika angeboten wird. Der ROASaurus-Connector für Lightspeed liest Bestellungen nur über die C-Series-API, deshalb deckt er E-Series-Shops nicht ab.

Warum fehlen Lightspeed-Käufe bei Meta und TikTok?

Ein Pixel im Browser meldet einen Kauf nur, wenn der Browser des Käufers die Dankeseite lädt und das Pixel-Skript läuft. Das scheitert in mehreren häufigen Situationen:

• Ein Käufer zahlt per Weiterleitung, zum Beispiel mit iDEAL oder PayPal, und schließt den Tab, bevor die Dankeseite lädt.
• Ein Adblocker oder eine Datenschutzeinstellung des Browsers blockiert das Pixel-Skript.
• Der Besucher lehnt Marketing-Cookies ab, deshalb darf das Pixel nicht laden.
• Die Bestellung wird später bezahlt, zum Beispiel per Banküberweisung, wenn kein Browser beteiligt ist.
• Safari begrenzt, wie lange von Skripten gesetzte Cookies gelten, sodass der Browser einen älteren Anzeigenklick vergessen kann.

Wie gelangen Lightspeed-Bestellungen zu ROASaurus?

Wenn du auf Create webhook drückst, registriert ROASaurus in Lightspeed einen Webhook für die Gruppe orders und die Aktion updated, im JSON-Format. Ab dann ruft Lightspeed ROASaurus auf, wenn sich eine Bestellung ändert.

Warum ROASaurus die Bestellung erneut liest

Lightspeed fügt einem Webhook nur dann einen x-signature-Header hinzu, wenn eine App ihn erstellt hat. Ein Webhook, der wie hier mit einem einfachen API-Key erstellt wurde, ist nicht signiert. Deshalb enthält die Webhook-Adresse ein Token, das nur für deinen Shop gilt, und ROASaurus vertraut dem Payload nicht. Es liest die Bestellung und ihre Produkte aus der Lightspeed-API und prüft den Zahlungsstatus selbst.

Die 5-Minuten-Prüfung

Alle 5 Minuten fragt ROASaurus Lightspeed außerdem nach Bestellungen, die seit der letzten Prüfung aktualisiert wurden, mit 30 Minuten Überlappung, und erfasst die bezahlten Bestellungen, die es noch nicht hat. Da diese Prüfung die Aktualisierungszeit verwendet, wird eine Bestellung, die Tage nach der Aufgabe bezahlt wurde, auch dann erfasst, wenn die Webhook-Zustellung fehlgeschlagen ist. Bestellungen, die ROASaurus bereits hat, werden ignoriert, sodass der Webhook und die Prüfung nie zwei Käufe erzeugen.

Auf Seiten von Lightspeed muss ein Webhook innerhalb von 5 Sekunden eine 2xx-Antwort erhalten. Fehlgeschlagene Zustellungen werden wiederholt, insgesamt bis zu 10 Versuche, und ein Webhook, dessen Fehlerquote 50 Stunden lang über 50% bleibt, wird deaktiviert. Die Prüfung alle 5 Minuten sorgt dafür, dass Bestellungen auch in einer solchen Lücke weiter ankommen.

Was liest ROASaurus aus einer Lightspeed-Bestellung aus?

Der Kaufwert enthält die MwSt.

Der Wert priceIncl von Lightspeed ist der Bestellpreis inklusive Steuern, und genau diesen Wert sendet ROASaurus. Deine Werbeplattformen melden deshalb Umsatz inklusive MwSt. So wirkt sich das bei 21% MwSt. aus:

Ein Break-even-ROAS basiert auf dem Umsatz ohne MwSt. Teile den ROAS der Plattform durch 1 plus deinen MwSt.-Satz, bevor du beide vergleichst.

Wie wird eine Lightspeed-Bestellung mit dem Anzeigenklick verknüpft?

Um eine Anzeige gutzuschreiben, braucht die Plattform die Klick-Kennungen des Besuchers, der bestellt hat: die Meta-Click-ID und die Browser-ID (fbc, fbp), die TikTok-Click-ID (ttclid) und das TikTok-Cookie (ttp). Das ROASaurus-Skript speichert sie für jeden Besucher, wenn er von einer Anzeige landet. Die Besucher-ID bekommt ROASaurus nicht aus der Lightspeed-Bestellung und verknüpft daher jede Bestellung auf anderem Weg mit einem Besucher. Es versucht drei Methoden, in dieser Reihenfolge:

Das Snippet übergibt außerdem die Bestellsumme, die Währung und die E-Mail-Adresse des Kunden. ROASaurus speichert einen Hash dieser E-Mail-Adresse beim Besucher, was hilft, die nächste Bestellung desselben Käufers zuzuordnen. ROASaurus wartet kurz, bevor es jeden Kauf sendet, damit das Event der Dankeseite zuerst eintreffen kann, und versucht die Zuordnung zum Sendezeitpunkt erneut.

Lightspeed variables used by the ROASaurus snippet (Tracking box)

order.information.number      order id and event id order-<number>
order.information.price_incl  value
order.information.currency    currency
order.customer.email          email, hashed on the visitor

Die Seite Orders zeigt in der Spalte Matched by, wie jede Bestellung verknüpft wurde: thank_you, email, ip oder not matched. Eine nicht zugeordnete Bestellung geht trotzdem mit ihren Bestelldaten an deine Werbeplattformen, aber ohne Click-Kennungen, und die ROASaurus-Attribution zeigt sie als direkt oder unbekannt.

Lightspeed-Käufe an Meta und TikTok senden

Jede bezahlte Bestellung wird zu einem Server-Event pro verbundener Plattform: ein Purchase für die Conversions API von Meta und ein CompletePayment für die Events API von TikTok, beide mit der Event-ID order-ORD01042. TikTok zeigt CompletePayment in seinen Berichten inzwischen als Purchase an. Wenn du die Option aktivierst, zusätzlich das Browser-Pixel zu laden, löst das Snippet auf der Dankeseite dieselben Events im Browser mit derselben Event-ID aus. Meta und TikTok behalten dann jeweils eine Kopie.

Dieselben Bestellungen gehen an Snapchat, Pinterest, Reddit, X, Microsoft Ads, Taboola, LinkedIn und die anderen Werbeplattformen, wenn du sie verbindest. Kauf-Conversions für Google Ads werden nur aus dem Shopify-Checkout gesendet, deshalb sendet ROASaurus sie nicht aus Lightspeed. Zur Einrichtung auf Seiten von Meta siehe den Leitfaden zur Meta Conversions API.

So richtest du das Conversion-Tracking für Lightspeed ein

1. Füge den Shop in ROASaurus hinzu

   Gehe zu Add a store, wähle Lightspeed eCom und gib deine Shop-Adresse ein. Der Tab Connection zeigt dir dann dein Script-Tag und das Snippet für die Dankeseite.

2. Füge das Skript auf jeder Seite hinzu

   Gehe im Lightspeed-Backoffice zu Settings › Website Settings › Web Extras › Custom JavaScript und füge das Script-Tag ein. Lightspeed führt diesen Code auf allen Seiten aus.

3. Das Snippet für die Dankeseite hinzufügen

   Aktiviere auf derselben Seite im Bereich Tracking den Status (Status on) und füge das Snippet ein. Lightspeed führt es nach einer Bestellung auf der Thank You page aus.

4. Einen API-Key erstellen

   Gehe zu Settings › Store Settings › Developers › New API key. Aktiviere den Schlüssel, setze den Haken bei Lesezugriff auf Bestellungen, speichere und wähle Show, um das Secret zu sehen.

5. Verbinde die API

   Gib im Tab Connection den Schlüssel, das Secret, die Region und die Shop-Sprache ein. Speichere, drücke Test connection und dann Create webhook.

6. Verbinde deine Werbeplattformen

   Nutze unter Tracking & platforms Connect with Facebook oder Add pixel für Meta und Add pixel für TikTok, mit dem Pixel-Code und einem Zugriffstoken für die Events API. Aktiviere die Option, zusätzlich das Browser-Pixel zu laden.

API key          (Settings › Store Settings › Developers)
API secret       (select Show next to the key)
Region           eu  →  api.webshopapp.com
                 us  →  api.shoplightspeed.com
Shop language    nl, en, de ...  (the code in your API addresses)

Einwilligung

Außerhalb von Shopify liest das ROASaurus-Skript die Entscheidung des Besuchers aus gängigen Einwilligungs-Tools: Cookiebot, OneTrust, IAB-TCF-Bannern und Google consent mode. Bei einem anderen Cookie-Banner rufst du tlq('consent', true) auf, wenn der Besucher Marketing-Cookies akzeptiert, und tlq('consent', false), wenn er sie ablehnt. Solange der Besucher nicht zustimmt, hat er keine Besucher-ID und keine Click-IDs, und es werden keine Browser-Pixel ausgelöst. Die bezahlte Bestellung wird trotzdem vom Server gesendet, mit gehashten Kundendaten aus der Bestellung sowie der IP-Adresse und dem Browser der Bestellung. Die Hilfeseite zur Einwilligung erklärt die Details.

Wie testest du das Conversion-Tracking für Lightspeed?

• Öffne deinen Shop mit ?roasaurus=connected in der Adresse. Ein Hinweis bestätigt, dass das Skript läuft. ?roasaurus=debug schreibt in die Browser-Konsole, was es sendet.
• Im Event log sollten Seitenaufrufe unter Collected events eine Besucher-ID zeigen.
• Gib eine Bestellung auf und stelle sicher, dass ihr Zahlungsstatus paid ist. Unter Collected events sollte das Event log dann einen Purchase mit deiner Bestellnummer in den Daten zeigen. Fehlt er, prüfe, ob Status im Bereich Tracking aktiviert ist.
• Im Tab Connection zeigt Last order received die Bestellung und Last sync die letzte Prüfung im 5-Minuten-Takt, samt einem eventuellen Fehler von Lightspeed.
• Unter Server deliveries im Event log erhält jede verbundene Plattform eine Zeile mit dem Status sent und der Antwort der Plattform.

Um das Event in Meta zu sehen, füge den Code aus Events Manager › Test events in das Feld Test event code deines Meta-Pixels in ROASaurus ein und entferne ihn, wenn du fertig bist. Die TikTok-Pixel-Einstellungen in ROASaurus haben dasselbe Feld.

Grenzen und Sonderfälle

• Nur C-Series. Shops mit Lightspeed eCom E-Series können diesen Connector nicht nutzen.
• Nur bezahlte Bestellungen. Eine teilweise bezahlte Bestellung wird gesendet, wenn ihr Zahlungsstatus auf paid wechselt.
• Verspätete Zahlungen und das 7-Tage-Limit von Meta. Meta akzeptiert Server-Events bis zu 7 Tage nach der Event-Zeit. ROASaurus verwendet den Erstellungszeitpunkt der Bestellung, daher lehnt Meta eine Bestellung ab, die mehr als 7 Tage nach der Aufgabe bezahlt wird.
• Käufe im Browser vor der Zahlung. Das Snippet der Dankeseite läuft, wenn die Bestellung aufgegeben wird, daher melden die Browser-Pixel eine Bestellung per Banküberweisung, bevor sie bezahlt ist. Kommt die Zahlung mehr als 48 Stunden später, können Meta und TikTok die Browser- und die Server-Kopie nicht zusammenführen.
• Stornierungen und Erstattungen werden nicht gesendet. Ein einmal gesendeter Kauf bleibt in der Werbeplattform.
• Nur Seitenaufrufe, ohne Code. Produktansichten und Warenkorb-Hinzufügungen werden nur in Shopify automatisch erkannt. In Lightspeed kann ein Entwickler sie mit einem tlq-Track-Aufruf senden.
• API-Limits. Lightspeed erlaubt pro API-Key 300 Anfragen pro 5 Minuten, 3,000 pro Stunde und 12,000 pro Tag. Wenn ein anderes Tool denselben Key nutzt, teilen sie sich diese Limits. Lightspeed bittet darum, für einen zweiten Key Kontakt aufzunehmen.

Die Integrationsseite für Lightspeed listet die Fakten zur Verbindung an einem Ort auf, und die Hilfeseite für andere Webshops vergleicht Lightspeed mit den anderen Plattformen, mit denen sich ROASaurus verbindet.

Quellen

1. Lightspeed eCom (C-Series) Help Center: Adding a web tracking code
2. Lightspeed eCom (C-Series) Help Center: Creating API keys
3. Lightspeed eCom developers: Webhooks
4. Lightspeed eCom developers: Order
5. Lightspeed eCom developers: Rate limiting

In ROASaurus

• Lightspeed-Integration
• Hilfe: Wix, Lightspeed und andere Webshops
• Server-Side-Tracking
• Meta-Integration

Weiterlesen