Verfolgung

Sales-Tracking ist die Verbindung zwischen dem, was Clerk den Besuchern anzeigt, und den Bestellungen, die sie aufgeben. Ohne Sales-Tracking kann Clerk nicht von echten Käufen lernen, Empfehlungen personalisieren oder eine präzise Umsatz-Zuordnung im Dashboard anzeigen.

In diesem Artikel wird erklärt, wie das Tracking auf API-Ebene funktioniert, wie man es einrichtet und wie man es debuggt, wenn Bestellungen nicht korrekt registriert werden.

Funktionsweise #

Jede getrackte Bestellung in Clerk durchläuft eine Kette aus drei verbundenen Komponenten.

Besucher-ID #

Wenn ein Besucher den Webshop betritt, generiert Ihr Server eine anonyme Sitzungs-ID und fügt diese in jede API-Anfrage während dieser Sitzung ein. So kann Clerk die Browsing-Aktivität des Besuchers – die Produkte, die er gesehen und angeklickt hat – mit der Bestellung verknüpfen, die er schließlich aufgibt.

In einer Clerk.js-Integration wird die Besucher-ID automatisch generiert und verwaltet. Bei einer direkten API-Integration sind Sie dafür verantwortlich, sie zu erstellen, zu speichern (z. B. in einer Session-Variable) und sie konsistent bei allen Aufrufen zu verwenden.

Labels #

Jeder API-Aufruf, der Ergebnisse zurückliefert – Suchergebnisse, Empfehlungen, Email-Ergebnisse – muss einen labels-Parameter enthalten. Das ist ein Array aus mindestens einem beschreibenden String, wie ["Homepage - Trending"] oder ["Search - Predictive"], das angibt, welches Element die Produkte angezeigt hat.

Wenn ein Besucher ein Produkt anklickt und später eine Bestellung auslöst, verwendet Clerk das Label vom Klick, um den Verkauf auf das Element zurückzuverfolgen, das ihn ausgelöst hat. Dies ist die Grundlage für die Umsatz-Attribution in den Analysen.

Labels, die fehlen, bei allen Elementen identisch oder zu generisch sind, machen es unmöglich für Clerk, zu unterscheiden, welches Element einen Verkauf beeinflusst hat. Das ist eine der häufigsten Ursachen für fehlende oder fehlerhafte Attribution.

Sale-Call #

Wenn der Besucher eine Bestellung aufgibt, verknüpft ein POST-Request an log/sale die Bestellung mit der Besucher-ID. Clerk kann nun die gesamte Kette verbinden: Dieser Besucher hat Produkte über Element X (das Label) gesehen, 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 einer Clerk.js-Integration geschieht das automatisch. Bei einer API-Integration müssen Sie jedes Mal, wenn ein Besucher ein Clerk-Produkt anklickt, log/click aufrufen – Details siehe API-Anleitung.

Diese Kette — Label → Klick → Verkauf — treibt sowohl die Personalisierung als auch die Umsatz-Analyse in my.clerk.io an.

Was Clerk speichert #

Jeder erfasste Verkauf enthält:

• Eine einzigartige Verkaufs-ID
• Produkt-IDs, Mengen und Stückpreise
• Die Besucher-ID (verknüpft den Verkauf mit der 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 einmalig nach einem erfolgreichen Kauf 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, wenn eine Bestellung abgeschlossen ist. Verwenden Sie dabei dieselbe Besucher-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 Stückpreis eines Einzelartikels. Clerk multipliziert diesen intern mit quantity zur Umsatzberechnung. Senden Sie nicht die Rechnungszeile als Summe.

Die vollständigen Details zur Generierung und Persistierung von Besucher-IDs während einer Sitzung finden Sie in der API-Anleitung.

Clerk.js #

Clerk.js verwaltet die Besucher-ID automatisch und übernimmt den log/sale-Aufruf für Sie. Fügen Sie folgenden Snippet auf Ihrer Bestellbestätigungsseite ein und ersetzen Sie die Platzhalterwerte 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 das Snippet beim Laden der Seite und sendet die Verkaufsdaten an die API, wobei die gleiche Besucher-ID verwendet wird, die während der gesamten Sitzung bereits getrackt wurde.

Überprüfung der Funktion #

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

Developers > Logs — Alle Fehler vom Tracking-Aufruf werden hier in Echtzeit angezeigt. Dies ist der schnellste Ort, um fehlerhafte Requests zu erkennen.

Data > Orders — Bestätigte getrackte Bestellungen erscheinen hier. Klicken Sie eine Bestellung an, um zu sehen, welche Produkte getrackt wurden und ob Clerk sie identifizieren konnte. Falls zu einem Produkt ein Platzhalterbild angezeigt wird, stimmt die Produkt-ID im Sale-Call nicht mit einer ID in Ihrem Katalog überein.

Data > Visitors — Suchen Sie nach einer Besucher-ID, um deren vollständige Sitzung einzusehen: Welche Produkte wurden angesehen, welche Clerk-Elemente wurden geklickt und welche Bestellungen wurden ausgelöst. In einer Clerk.js-Integration können Sie zum Testen eine bestimmte Besucher-ID erzwingen, indem Sie ?clerk_visitor=VISITOR_ID an eine beliebige Seiten-URL anhängen — Clerk.js verwendet dann diese ID für die Sitzung, was eine lückenlose Nachverfolgung eines Testablaufs ermöglicht.

Das Health Dashboard zeigt einen Gesamt-Statusindikator für das Sales-Tracking. Rot bedeutet, es wurden in letzter Zeit keine getrackten Bestellungen empfangen.

Fehlerbehebung #

Gehen Sie wie folgt vor, wenn Bestellungen nicht korrekt getrackt werden.

Protokolle prüfen #

Gehen Sie zu Developers > Logs und suchen Sie nach Fehlern vom log/sale-Endpoint. Dies gilt für sowohl API- als auch Clerk.js-Setups – jeder abgelehnte Request taucht sofort mit einer Fehlermeldung auf.

Für Clerk.js-Setups führen Sie außerdem Clerk("debug") in der Browser-Konsole aus, bevor Sie eine Testbestellung tätigen. Dies aktiviert den Debug-Modus, durch den Clerk.js detaillierte Informationen zu jedem Tracking-Aufruf protokolliert — einschließlich verwendeter Besucher-ID, zugehöriger Labels der Ergebnis-Aufrufe und aufgetretener Fehler. Suchen Sie im Konsolen-Output nach Einträgen mit Präfix [Clerk].

API-Antwort verifizieren #

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

{"status": "ok"}

Eine fehlerhafte Antwort enthält eine Fehlermeldung mit einer Beschreibung, zum Beispiel:

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

Lesen Sie die Fehlermeldung — sie zeigt meistens direkt auf das Problem.

API-Setup: Loggen Sie die rohe HTTP-Antwort vom log/sale-Aufruf in Ihrem Server-Code. Falls noch nicht geschehen, testen Sie den Aufruf direkt mit einem bekannten, korrekten 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, die Produktionsaufrufe aber nicht, vergleichen Sie beide Payloads – der Unterschied gibt Aufschluss über das Problem.

Clerk.js-Setup: Öffnen Sie die Browser-DevTools, wechseln Sie zum Netzwerk-Tab und filtern Sie nach clerk. Platzieren Sie eine Testbestellung und suchen Sie nach einem Request, der mit sale?key=... beginnt. Klicken Sie darauf und prüfen Sie dort die Antwort.

Request-Parameter prüfen #

Wenn Bestellungen nicht getrackt oder nicht korrekt zugeordnet werden, überprüfen Sie Folgendes in Ihrer gesamten Einrichtung:

API-Schlüssel — Vergewissern Sie sich, dass key mit dem Public API Key in Developers > API Keys übereinstimmt. Ein falscher Schlüssel führt sofort zu einem Authentifizierungsfehler.

Besucher-ID — Kontrollieren Sie, dass visitor vorhanden ist und denselben Wert wie bei vorherigen Ergebnis-Aufrufen innerhalb dieser Sitzung hat. Wird bei jeder Anfrage eine neue ID generiert oder ist sie an einem Ort gespeichert, der vor dem Checkout gelöscht wird, stimmt die ID beim Sale-Call nicht mit der beim Klick verknüpften ID überein.

Labels — Stellen Sie sicher, dass jeder ergebnisliefernde Aufruf vorher in der Sitzung ein labels-Array mit einem eindeutigen Label für jedes Element enthalten hat. Wenn Labels fehlen oder bei allen Elementen identisch sind, erfasst Clerk den Verkauf, kann ihn aber keinem bestimmten Element zuordnen.

Produkt-IDs — Überprüfen Sie, ob die IDs im products-Array mit den IDs übereinstimmen, die Clerk in seinem Katalog hat. Suchen Sie eine der IDs in Data > Products zum Abgleich. Falls sie nicht auffindbar ist, senden Sie wahrscheinlich Varianten-IDs oder SKUs statt Elternprodukt-IDs.

Sale-ID — Vergewissern Sie sich, dass der Wert in sale für jede Bestellung eindeutig ist und nicht mehrfach verwendet wird. Clerk ignoriert doppelte Sale-IDs stillschweigend.

Kein Aufruf gemacht #

API-Setup: Der Aufruf wird nicht von Ihrem Server ausgelöst. Prüfen Sie Ihren Handler für den Abschluss einer Bestellung – wird er nach einem erfolgreichen Kauf tatsächlich erreicht, und wird kein Fehler ausgelöst, der den Tracking-Aufruf verhindert? Fügen Sie temporäres Logging um den log/sale-Aufruf ein, um sicherzustellen, dass er ausgeführt wird.

Clerk.js-Setup: Die Clerk.js-Bibliothek läuft auf der Bestätigungsseite nicht. Öffnen Sie die Browser-Konsole und tippen Sie Clerk. Falls Sie folgenden Fehler sehen, wurde die Bibliothek nicht geladen:

Uncaught ReferenceError: Clerk is not defined

Stellen Sie sicher, dass das Clerk.js-Tracking-Skript in der Bestätigungsseiten-Vorlage eingebunden ist und nicht von einem anderen Skript oder durch ein Cookie-Consent-Tool blockiert wird.

Kein Clerk-Einfluss #

Wenn der Sale-Call erfolgreich ist, aber keine Bestellungen als von Clerk beeinflusst in den Analysen angezeigt werden, hat Clerk die Bestellung erfasst, konnte sie jedoch keiner Sitzung oder keinem Element zuordnen.

log/click wird nicht aufgerufen — Die häufigste Ursache. Clerk kann einen Verkauf keinem Element zuordnen, wenn nicht vorher ein Klick getrackt wurde. Bei einer Clerk.js-Integration ist das Klick-Tracking automatisch – achten Sie darauf, dass die Bibliothek auf den Seiten geladen ist, auf denen Clerk-Ergebnisse angezeigt werden. Bei einer API-Integration stellen Sie sicher, dass Ihr Code jedes Mal log/click aufruft, wenn ein Besucher ein von Clerk angezeigtes Produkt anklickt und dass dieser Request auch tatsächlich an die API gesendet wird (prüfen Sie Server-Logs oder Antworten).

Fehlende oder ungültige Labels — Prüfen Sie, dass jeder ergebnisliefernde Aufruf und jeder log/click-Aufruf ein gültiges labels-Array enthält. Sind Labels fehlend, leer oder bestehen nur aus Leerzeichen, kann Clerk nicht bestimmen, mit welchem Element der Besucher interagiert hat; der Verkauf wird dann nicht zugeordnet.

API-Setup: Überprüfen Sie, dass die Besucher-ID im log/sale-Aufruf exakt mit der in log/click beim Produktklick übereinstimmt. Schon kleine Unterschiede – anderes Format, zusätzliches Zeichen, neu generierte ID – unterbrechen die Verbindung.

Clerk.js-Setup: Besucher-IDs werden automatisch verwaltet, aber die Verbindung kann abbrechen, wenn das Tracking-Skript auf einer oder mehreren Seiten im Checkout-Prozess fehlt. Prüfen Sie, dass Clerk.js auf allen Seiten zwischen Produkt- und Bestellbestätigungsseite geladen wird.

Häufige Fehler #

Dies sind die häufigsten Ursachen dafür, dass Sales-Tracking fehlschlägt oder die Attribution nicht korrekt funktioniert.

Ungültige Produkt-Syntax #

Produkt-IDs müssen als derselbe Typ wie im Datenfeed gesendet werden. Verwenden Sie dort Integer, müssen sie auch im Sale-Call Integer sein – nicht Strings. Wird "id": "123" gesendet, aber Clerk erwartet "id": 123, schlägt der Aufruf fehl.

Der Wert in products muss außerdem gültiges JSON sein. Maskierte oder doppelt kodierte Strings wie "products": "[{\"id\":\"123\"}]" werden nicht korrekt verarbeitet.

Fehlende Argumente #

Die Argumente key, sale und products sind alle erforderlich. Fehlt eines, wird ein Fehler zurückgegeben. Das products-Array muss mindestens ein Element enthalten.

Clerk.js nicht geladen #

Fehlt die Clerk.js-Bibliothek auf der Bestätigungsseite oder wird sie am Ausführen gehindert, erfolgt kein Sale-Call. Zwei häufige Ursachen:

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

Falsche Produkt-IDs #

Tracken Sie die Eltern-Produkt-ID, nicht die Varianten-ID. Kauft ein Besucher ein rotes T-Shirt in Größe M, tracken Sie die Eltern-ID — nicht die der spezifischen Variante. Dieselbe ID muss sowohl beim Klick-Tracking als auch beim Sale-Call verwendet werden. Abweichende IDs unterbrechen die Attribution, auch wenn beide Aufrufe erfolgreich sind.

Besucher-ID wechselt #

Bei einer API-Integration muss die Besucher-ID von der ersten Seitenansicht bis zum Sale-Call gleich bleiben. Wird sie bei jedem Laden der Seite neu generiert, werden Klick und Verkauf unterschiedlichen Sitzungen zugeordnet, und Clerk kann sie nicht verknüpfen.

In einer Clerk.js-Integration wird dies automatisch gehandhabt, kann aber fehlschlagen, wenn das Tracking-Script auf einer oder mehreren Seiten im Checkout-Prozess fehlt.

Stückpreis stimmt nicht #

price im products-Array muss der Stückpreis eines Einzelartikels sein. Clerk multipliziert diesen mit quantity zur Umsatzberechnung. Wird eine bereits multiplizierte Zeilensumme gesendet, entstehen in der Analyse zu hohe Umsatzzahlen.

Wiederverwendete Verkaufs-IDs #

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

Nutzen Sie ein serverseitiges Flag oder einen Sitzungsmarker, um sicherzustellen, dass der Tracking-Aufruf pro Bestellung nur einmal erfolgt.

Fehlende Besucherdaten #

Werden weder visitor noch email im Sale-Call mitgesendet, erfasst Clerk die Bestellung, kann sie aber keiner Sitzung oder keinem Kundenprofil zuordnen. Die Bestellung erscheint in Data > Orders, wird aber in den Analysen nie als von Clerk beeinflusst angezeigt.

Inkludieren Sie immer den visitor-Parameter. Wenn verfügbar, verbessern Sie Personalisierung über künftige Sitzungen für den Kunden, indem Sie zusätzlich email und customer angeben.

Besucher-Tracking deaktivieren #

Um das Tracking für einen bestimmten Besucher zu stoppen — z. B. wenn er im Cookie-Banner alle Tracking-Optionen abgelehnt hat — setzen Sie "visitor": null in allen API-Aufrufen für diese Sitzung. Clerk verarbeitet die Requests normal, protokolliert aber keine Aktivitäten gegen ein Besucherprofil.

In einer Clerk.js-Integration setzen Sie dies stattdessen in der Konfiguration:

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

Auch wenn das Besucher-Tracking deaktiviert ist, werden Verkäufe weiterhin protokolliert. Clerk erhält die Bestelldaten und beinhaltet sie in den Analysen, aber ohne Sitzungs-Kontext — keine Klick-Historie, keine angesehenen Produkte, keine Element-Zuordnung. Clerk weiß dann nur, was gekauft wurde, aber nicht, wie der Besucher dorthin gelangt ist.