Verkaufsverfolgung

Verkaufs-Tracking ist die Verbindung zwischen dem, was Clerk den Besuchern anzeigt, und den Bestellungen, die sie aufgeben. Ohne diese Funktion kann Clerk nicht aus echten Käufen lernen, Empfehlungen personalisieren oder eine genaue Umsatzzuordnung im Dashboard anzeigen.

Dieser Artikel erklärt, wie das Tracking auf API-Ebene funktioniert, wie es eingerichtet wird und wie man es debuggt, wenn Bestellungen nicht korrekt erfasst werden.

Funktionsweise #

Jede erfasste Bestellung in Clerk durchläuft eine Kette von drei miteinander verbundenen Elementen.

Visitor ID #

Wenn ein Besucher im Webshop ankommt, erzeugt Ihr Server eine anonyme Sitzungs-ID und fügt sie jedem API-Aufruf während dieser Sitzung hinzu. Dies ermöglicht es Clerk, die Aktivitäten eines Besuchers beim Durchstöbern – die von ihm angesehenen und angeklickten Produkte – mit der späteren Bestellung zu verknüpfen.

In einem Clerk.js-Setup wird die Visitor ID automatisch generiert und verwaltet. In einem direkten API-Setup sind Sie dafür verantwortlich, sie zu erstellen, zu speichern (z. B. in einer Sitzungsvariable) und bei allen Aufrufen konsistent zu übergeben.

Labels #

Jeder API-Aufruf, der Ergebnisse zurückgibt – Suchtreffer, Empfehlungen, E-Mail-Ergebnisse – muss einen labels-Parameter enthalten. Dies ist ein Array mit mindestens einem beschreibenden Text, wie z. B. ["Homepage - Trending"] oder ["Search - Predictive"], das angibt, welches Element diese Produkte angezeigt hat.

Wenn ein Besucher auf ein Produkt klickt und später eine Bestellung aufgibt, verwendet Clerk das Label des Klicks, um den Verkauf dem auslösenden Element zuzuordnen. Dies bildet die Grundlage für die Umsatzzuordnung in der Analyse.

Labels, die fehlen, bei allen Elementen identisch oder zu allgemein sind, machen es Clerk unmöglich, zu bestimmen, welches Element einen Verkauf beeinflusst hat. Dies ist einer der häufigsten Gründe, warum die Attribution falsch aussieht oder ganz fehlt.

Sale Call #

Wenn der Besucher eine Bestellung aufgibt, verknüpft ein POST-Request an log/sale die Bestellung mit der Visitor ID. Clerk kann nun die gesamte Kette verbinden: Dieser Besucher hat Produkte von Element X (das Label) angezeigt bekommen, eines angeklickt und einen Kauf abgeschlossen.

Damit diese Kette funktioniert, muss jeder Klick auf ein von Clerk angezeigtes Produkt ebenfalls über log/click protokolliert werden. In einem Clerk.js-Setup geschieht dies automatisch. In einem API-Setup müssen Sie bei jedem Klick auf ein Clerk-Produkt log/click aufrufen – siehe API guide für Details.

Diese Kette – Label → Klick → Verkauf – treibt sowohl die Personalisierung als auch die Umsatzanalyse in my.clerk.io an.

Was Clerk speichert #

Jede erfasste Bestellung enthält:

• Eine eindeutige Verkaufs-ID
• Produkt-IDs, Stückzahlen und Einzelpreise
• Die Visitor ID (verknüpft den Verkauf mit ihrer Sitzung)
• Kunden-E-Mail und Kunden-ID – optional, ermöglicht Sitzungs-übergreifende Personalisierung

Einrichtung #

Platzieren Sie den Sales-Tracking-Aufruf auf der Bestellbestätigungsseite, die nach einem erfolgreichen Kauf einmalig geladen wird. Platzieren Sie ihn nicht auf der Warenkorbseite oder an einem anderen Punkt im Checkout-Prozess.

API #

Senden Sie einen POST-Request an log/sale von Ihrem Server, sobald eine Bestellung abgeschlossen ist. Übergeben Sie die gleiche Visitor ID, die während der gesamten Sitzung verwendet wurde.

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "YOUR_PUBLIC_API_KEY",
    "sale": 567,
    "products": [
      {"id": 12793, "price": 99.95, "quantity": 2},
      {"id": 1546, "price": 14.00, "quantity": 1}
    ],
    "email": "luke@skywalker.com",
    "customer": 1234,
    "visitor": "abc123"
  }' \
  https://api.clerk.io/v2/log/sale

price ist immer der Einzelpreis eines einzelnen Artikels. Clerk multipliziert diesen intern mit quantity zur Umsatzberechnung. Senden Sie nicht die Zeilensumme.

Siehe den API guide für vollständige Details zur Generierung und Speicherung von Visitor IDs innerhalb einer Sitzung.

Clerk.js #

Clerk.js verwaltet die Visitor ID automatisch und übernimmt den log/sale-Aufruf für Sie. Fügen Sie folgenden Code-Snippet auf Ihrer Bestellbestätigungsseite ein und ersetzen Sie die Platzhalter durch die Variablen Ihrer Plattform:

<span
  class="clerk"
  data-api="log/sale"
  data-sale="ORDER_ID"
  data-email="CUSTOMER_EMAIL"
  data-customer="CUSTOMER_ID"
  data-products='[{"id": 12, "quantity": 1, "price": 99.95}, {"id": 54, "quantity": 2, "price": 9.50}]'>
</span>

Clerk.js erkennt den Snippet beim Laden der Seite und sendet die Verkaufsdaten an die API – mit derselben Visitor ID, die während der gesamten Sitzung verfolgt wurde.

Überprüfung der Funktion #

Überprüfen Sie nach einer Testbestellung diese drei Stellen.

Developers > Logs — Alle Fehler aus dem Tracking-Aufruf werden hier in Echtzeit angezeigt. Dies ist die schnellste Stelle, um eine falsch konfigurierte Anfrage zu erkennen.

Data > Orders — Bestätigte, erfasste Bestellungen erscheinen hier. Klicken Sie auf eine Bestellung, um zu sehen, welche Produkte getrackt wurden und ob Clerk sie identifizieren kann. Wenn ein Produkt ein Platzhalterbild anzeigt, stimmt die Product ID im Sale Call mit keinem Produkt im Katalog überein.

Data > Visitors — Suchen Sie nach einer Visitor ID, um die vollständige Sitzung einzusehen: Welche Produkte sie angesehen haben, welche Clerk-Elemente sie angeklickt haben und welche Bestellungen sie aufgegeben haben. In einem Clerk.js-Setup können Sie beim Testen eine bestimmte Visitor ID forcieren, indem Sie ?clerk_visitor=VISITOR_ID an eine beliebige Seiten-URL anhängen – Clerk.js verwendet für diese Sitzung dann diese ID, was einen vollständigen Testablauf einfach nachvollziehbar macht.

Das Health dashboard zeigt einen Statusindikator für das Sales Tracking. Rot bedeutet, dass kürzlich keine getrackten Bestellungen empfangen wurden.

Fehlerbehebung #

Gehen Sie diese Schritte durch, wenn Verkäufe nicht korrekt getrackt werden.

Logs überprüfen #

Gehen Sie zu Developers > Logs und suchen Sie nach Fehlern vom log/sale-Endpunkt. Das gilt sowohl für API- als auch Clerk.js-Setups – jede abgelehnte Anfrage erscheint hier sofort mit einer Fehlermeldung, die den Fehler beschreibt.

Für Clerk.js-Setups führen Sie außerdem Clerk("debug") in der Browser-Konsole aus, bevor Sie eine Testbestellung aufgeben. Dies aktiviert den Debug-Modus, sodass Clerk.js detaillierte Informationen zu jedem Tracking-Aufruf ausgibt – einschließlich der verwendeten Visitor ID, der an Ergebniscalls angehängten Labels und aller aufgetretenen Fehler. Suchen Sie im Konsolenauszug nach Einträgen mit dem Präfix [Clerk].

API-Antwort prüfen #

Der log/sale-Endpunkt gibt immer eine Antwort zurück. Eine erfolgreiche sieht so aus:

{"status": "ok"}

Ein fehlgeschlagener Rückruf gibt einen Fehler und eine Beschreibung der Ursache zurück, zum Beispiel:

{"status": "error", "error": "Missing required argument: sale"}

Lesen Sie die Fehlermeldung – sie zeigt meist direkt auf das Problem.

API-Setup: Protokollieren Sie die Roh-HTTP-Antwort des log/sale-Aufrufs in Ihrem Server-Code. Falls Sie dies noch nicht tun, testen Sie den Aufruf direkt mit einem bekannten gültigen Payload:

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "YOUR_PUBLIC_API_KEY",
    "sale": 999,
    "products": [{"id": 12793, "price": 99.95, "quantity": 1}],
    "visitor": "test-visitor-1"
  }' \
  https://api.clerk.io/v2/log/sale

Wenn dies funktioniert, in der Produktivumgebung aber nicht, vergleichen Sie beide Payloads genau – der Unterschied weist auf das Problem hin.

Clerk.js-Setup: Öffnen Sie in den Browser DevTools den Tab Netzwerk und filtern Sie nach clerk. Geben Sie eine Testbestellung auf und suchen Sie nach einer Anfrage, die mit sale?key=... beginnt. Klicken Sie darauf und prüfen Sie die Antwort.

Request-Parameter prüfen #

Wenn Bestellungen nicht getrackt werden oder keine korrekte Attribution erfolgt, prüfen Sie Folgendes in Ihrem Setup:

API key — Prüfen Sie, dass key mit Ihrem Public API Key aus Developers > API Keys übereinstimmt. Ein falscher Key führt sofort zu einem Authentifizierungsfehler.

Visitor ID — Prüfen Sie, dass visitor vorhanden ist und denselben Wert hat, wie in den ergebnisliefernden Aufrufen derselben Sitzung. Wenn Sie bei jedem Request eine neue ID erzeugen oder sie an einer Stelle speichern, die vor dem Checkout geleert wird, stimmt die ID im Sale Call nicht mehr mit der des Klicks überein.

Labels — Stellen Sie sicher, dass alle ergebnisliefernden Aufrufe vor dem Verkauf ein labels-Array mit einmaligen Labels für jedes Element enthielten. Fehlen Labels oder sind sie elementübergreifend identisch, zeichnet Clerk zwar den Verkauf auf, kann ihn aber keinem spezifischen Element zuordnen.

Product IDs — Vergewissern Sie sich, dass die IDs im products-Array mit den IDs übereinstimmen, die Clerk in seinem Katalog hat. Suchen Sie eine der IDs in Data > Products, um dies zu bestätigen. Wenn Sie sie nicht finden, senden Sie vermutlich Varianten-IDs oder SKUs statt der übergeordneten Produkt-IDs.

Sale ID — Prüfen Sie, dass der Wert für sale für jede Bestellung eindeutig und nicht mehrfach für verschiedene Anforderungen verwendet wird. Clerk ignoriert doppelte Verkauf-IDs stillschweigend.

Kein Call ausgeführt #

API-Setup: Der Call wird nicht von Ihrem Server ausgelöst. Prüfen Sie Ihren Bestellabschluss-Handler – stellen Sie sicher, dass er nach einem erfolgreichen Kauf tatsächlich aufgerufen wird und keine Exception den Tracking-Aufruf unterdrückt. Fügen Sie temporäres Logging um den log/sale-Call ein, um die Ausführung zu bestätigen.

Clerk.js-Setup: Die Clerk.js-Bibliothek läuft nicht auf der Bestätigungsseite. Öffnen Sie die Browser-Konsole und geben Sie Clerk ein. Wenn Sie folgende Fehlermeldung sehen, wurde die Bibliothek nicht geladen:

Uncaught ReferenceError: Clerk is not defined

Stellen Sie sicher, dass das Clerk.js-Tracking-Skript im Template der Bestätigungsseite enthalten und nicht von einem anderen Skript oder einem Cookie-Consent-Tool blockiert wird.

Keine Clerk-Zuordnung #

Wenn der Sale Call erfolgreich ist, aber keine Bestellungen als Clerk-beeinflusst in der Analyse erscheinen, hat Clerk die Bestellung aufgezeichnet, konnte sie jedoch keiner Sitzung oder keinem Element zuordnen.

log/click wird nicht aufgerufen — Die häufigste Ursache. Clerk kann einen Verkauf nur dann einem Element zuordnen, wenn vor dem Kauf ein Klick geloggt wurde. In einem Clerk.js-Setup erfolgt das Klick-Tracking automatisch – prüfen Sie, ob die Bibliothek auf den Seiten, auf denen Clerk-Ergebnisse angezeigt werden, geladen ist. In einem API-Setup stellen Sie sicher, dass Ihr Code bei jedem Klick auf ein Clerk-Produkt log/click aufruft und die Anfrage tatsächlich die API erreicht (prüfen Sie Server-Logs oder Antwort).

Fehlende oder ungültige Labels — Prüfen Sie, dass jeder ergebnisliefernde Call und jeder log/click-Call ein gültiges labels-Array enthält. Fehlen Labels, sind sie leer oder enthalten nur Leerzeichen, kann Clerk nicht bestimmen, mit welchem Element der Besucher interagiert hat, und der Verkauf wird nicht zugeordnet.

API-Setup: Prüfen Sie, dass die Visitor ID im log/sale-Call exakt mit der im log/click-Call übereinstimmt, als der Besucher das Produkt angeklickt hat. Schon ein kleiner Unterschied – ein anderes Format, ein zusätzliches Zeichen oder eine neu generierte ID – unterbricht die Verbindung.

Clerk.js-Setup: Visitor IDs werden automatisch verwaltet, aber die Verbindung kann unterbrochen werden, wenn das Tracking-Skript auf einer oder mehreren Seiten im Checkout-Prozess fehlt. Prüfen Sie, dass Clerk.js auf sämtlichen Seiten zwischen Produktseite und Bestätigungsseite geladen ist.

Häufige Fehler #

Dies sind die häufigsten Ursachen dafür, dass das Verkaufs-Tracking nicht funktioniert oder Attribution nicht korrekt läuft.

Ungültige Produkt-Syntax #

Produkt-IDs müssen als derselbe Typ gesendet werden wie auch im Daten-Feed verwendet. Verwenden Sie dort Ganzzahlen, müssen sie auch im Sale Call Integers sein – nicht Strings. Senden Sie "id": "123", wenn Clerk "id": 123 erwartet, führt dies zum Fehler.

Der Wert von products muss zudem gültiges JSON sein. Escapete oder doppelt kodierte Strings wie "products": "[{\"id\":\"123\"}]" können nicht korrekt geparst werden.

Fehlende Argumente #

Die Argumente key, sale und products sind alle erforderlich. Wird eines davon weggelassen, gibt es einen Fehler. Das products-Array muss mindestens ein Element enthalten.

Clerk.js nicht geladen #

Fehlt die Clerk.js-Bibliothek auf der Bestätigungsseite oder ist sie blockiert, wird kein Sale Call ausgelöst. Zwei häufige Ursachen:

• Das Tracking-Skript ist nicht im Template der Bestätigungsseite eingebunden.
• Ein Cookie-Consent-Tool (wie z. B. iubenda im automatischen Blocking-Modus) blockiert cdn.clerk.io oder api.clerk.io. Setzen Sie beide Domains auf die Allowlist, damit Tracking nicht unterdrückt wird, wenn Besucher nicht essentielle Cookies ablehnen.

Falsche Produkt-IDs #

Tracken Sie die übergeordnete Produkt-ID, nicht die Varianten-ID. Kauft ein Besucher ein rotes T-Shirt in Größe M, muss die Parent-ID getrackt werden – nicht die ID dieser spezifischen Variante. Dieselbe ID muss im Klick-Tracking und im Sale Call verwendet werden. Unterschiedliche IDs zerstören die Attribution – auch wenn beide Aufrufe erfolgreich sind.

Änderungen der Visitor ID #

Im API-Setup muss die Visitor ID von der ersten Seitenansicht bis zum Sale Call gleich bleiben. Generieren Sie sie bei jedem Seitenaufruf neu, werden Klick und Verkauf unterschiedlichen Sitzungen zugeordnet und Clerk kann sie nicht verbinden.

Im Clerk.js-Setup wird dies automatisch gehandhabt, kann aber scheitern, wenn das Tracking-Skript auf einer oder mehreren Seiten im Checkout-Prozess fehlt.

Falscher Einzelpreis #

price im products-Array muss der Einzelpreis eines Artikels sein. Clerk multipliziert diesen Wert mit quantity zur Umsatzberechnung. Wird eine bereits multiplizierte Zeilensumme gesendet, entstehen in der Analyse verfälschte Umsatzwerte.

Wiederverwendete Sale IDs #

Clerk speichert nur den ersten Aufruf für eine gegebene Sale ID. Kann die Bestätigungsseite aktualisiert oder erneut besucht werden, feuert der Tracking-Aufruf erneut mit derselben Sale ID. Der zweite Aufruf wird stillschweigend ignoriert.

Verwenden Sie eine serverseitige Kennzeichnung oder eine Sitzungsmarke, um sicherzustellen, dass der Tracking-Aufruf nur einmal pro Bestellung ausgelöst wird.

Fehlende Visitor-Daten #

Wenn weder visitor noch email im Sale Call enthalten sind, wird die Bestellung bei Clerk aufgezeichnet, kann aber keiner Sitzung oder keinem Kundenprofil zugeordnet werden. Die Bestellung erscheint in Data > Orders, aber nie als von Clerk beeinflusst in der Analyse.

Fügen Sie immer den visitor-Parameter hinzu. Das Hinzufügen von email und customer, sofern verfügbar, verbessert zudem die Personalisierung über künftige Sitzungen des Kunden hinweg.

Deaktivierung von Visitor-Tracking #

Um das Tracking für einen bestimmten Besucher zu deaktivieren – etwa wenn er über ein Cookie-Consent-Banner alles Tracking abgelehnt hat – übergeben Sie "visitor": null in allen API-Calls dieser Sitzung. Clerk verarbeitet die Anfragen normal, protokolliert aber keine Aktivität für ein Besucherprofil.

Im Clerk.js-Setup wird dies stattdessen in der Konfiguration gesetzt:

Clerk('config', {
  key: 'YOUR_API_KEY',
  visitor: null
});

Bestellungen werden auch dann protokolliert, wenn das Visitor-Tracking deaktiviert ist. Clerk erhält die Bestelldaten und schließt sie in die Analyse ein, aber ohne jeglichen Sitzungs-Zusammenhang – keine Klick-Historie, keine angesehenen Produkte, keine Element-Attribution. Clerk weiß dann nur, was gekauft wurde; nicht, wie der Besucher dorthin gelangt ist.