Commerce-Tracking

Commerce-Tracking

MetriXs verfolgt Commerce fuer jede Website gleich, egal ob Sie Shopify, eine selbstgebaute Storefront oder einen serverseitigen Checkout betreiben. Es gibt keine commerce-spezifischen Spalten: Commerce ist nur eine Reihe von benutzerdefinierten Events mit einigen vereinbarten Eigenschaftsnamen. Wenn Sie Commerce auf einer Site aktivieren, zeigt das Dashboard Umsatz, durchschnittlichen Auftragswert (AOV), Konversionsrate, einen Checkout-Trichter und eine Top-Produkte-Aufschluesselung, alle durch diese Events getrieben.

Commerce auf einer Site aktivieren

1. Gehen Sie zu Einstellungen → Sites im Dashboard.
2. Finden Sie Ihre Site und schalten Sie Commerce auf An.
3. Waehlen Sie optional eine Anzeigewaehrung (Standard EUR; siehe unten).

Shopify-Sites haben Commerce standardmaessig an (das MetriXs-Web-Pixel feuert die Events fuer Sie); der Schalter und die Waehrung sind noch da, wenn Sie Commerce ausschalten oder die Anzeigewaehrung aendern moechten. Andere Sites aktivieren es hier und feuern die Events selbst. Ein Kopier-Einfuegen-Event-Snippet erscheint auf der Installieren & Verifizieren-Seite der Site, sobald Commerce an ist.

Das Event-Schema

Drei benutzerdefinierte Events bilden den Commerce-Trichter. Senden Sie sie von Ihrem Checkout in dieser Reihenfolge:

Event-Name	Wann feuern	Erforderliche Props
checkout_started	Besucher betritt den Checkout	total, currency
payment_submitted	Zahlungsdetails eingereicht	(keine)
order_completed	Bestellung ist aufgegeben (Dankesseite / Bestaetigung)	total, currency

Fuer order_completed koennen Sie auch eine items-Eigenschaft mit der Produkt-Aufschluesselung senden, sodass das Top-Produkte-Panel den Umsatz nach Produkt aufschluesseln kann.

Eigenschaftsnamen

• total (number), das Order-/Warenkorbtotal.
• currency (string, ISO 4217, z.B. EUR, USD, GBP), die Waehrung, in der total ist. MetriXs konvertiert es in EUR (siehe unten).
• items (string), ein JSON-kodiertes Array von { title, quantity, price } (ein Objekt pro Position).
• order_id (string, optional), Ihre interne Bestell-ID, als Referenz.

Umsatz wird in EUR gespeichert

MetriXs speichert gesamten Umsatz in EUR. Wenn ein Commerce-Event mit einer Nicht-EUR-currency eintrifft, konvertiert die Ingestion-Pipeline total (und jeden Position-price) in EUR mit taeglichen EZB-Referenzkursen vor dem Speichern und zeichnet die Originalwaehrung als currency_original auf. Das gespeicherte total ist daher immer EUR, sodass Umsatz und AOV auch fuer Multi-Waehrungs-Stores konsistent sind.

• Wenn Sie currency weglassen, nimmt MetriXs an, dass der Betrag bereits EUR ist (keine Konvertierung).
• Unbekannte Waehrungen werden als-is belassen (als EUR behandelt), sodass ein Tippfehler nie still Ihren Umsatz nullt.
• Die Kurse sind die taeglichen EZB-Referenzkurse, automatisch jeden Tag aktualisiert (ein Cron ruft den offiziellen EZB-Feed ab und speichert die Kurse in Redis). Wenn der Abruf fehlschlaegt oder der Cache kalt ist, faellt MetriXs auf eine statische Referenztabelle im Image zurueck, sodass die EUR-Normalisierung bei einem Upstream-Ausfall nie bricht. Referenzkurse sind keine Live-Handelskurse.

Anzeigewaehrung

Waehrend Umsatz in EUR gespeichert wird, koennen Sie pro Site eine andere Anzeige-Waehrung waehlen. MetriXs konvertiert die EUR-gespeicherten Betraege in Ihre Anzeigewaehrung im Dashboard mit denselben taeglichen EZB-Kursen, sodass Umsatz, AOV, das Umsatzdiagramm, der Trichter, Top-Produkte und die Umsatz-Spalte in den Quellen-/Standort-/Geraet-Panels alle in Ihrer gewaehlten Waehrung angezeigt werden.

• Standard: EUR (keine Konvertierung).
• Pro Site unter Einstellungen → Sites neben dem Commerce-Schalter einstellen. Die Liste deckt die haeufigen Waehrungen ab (USD, GBP, CHF, SEK, NOK, DKK, PLN, CZK, CAD, AUD, JPY, INR, CNY, BRL und mehr).
• Dies ist eine Anzeige-Einstellung; es aendert nicht, was gespeichert wird oder wie Sie Events senden. Senden Sie immer currency im Event fuer eine genaue EUR-Konvertierung.

Events von einem Browser-Checkout feuern

Nachdem das Tracker-Skript installiert ist, ist die globale window.metrixs(name, { props })-Funktion verfuegbar. Feuern Sie die Events von Ihrem Checkout-Flow:

// Besucher betritt den Checkout
window.metrixs('checkout_started', { props: { total: 49.99, currency: 'EUR' } })

// Zahlungsdetails eingereicht
window.metrixs('payment_submitted', { props: {} })

// Bestellung aufgegeben
window.metrixs('order_completed', {
  props: {
    total: 49.99,
    currency: 'EUR',
    items: JSON.stringify([
      { title: 'T-shirt', quantity: 2, price: 24.99 },
    ]),
  },
})

Verwenden Sie keepalive: true (oder einen navigator.sendBeacon-Fallback) beim order_completed-Aufruf, wenn Ihre Dankesseite schnell entlaedt.

Events serverseitig feuern (nach einem Zahlungs-Webhook)

Redirect-basierte Checkouts (Stripe, Mollie, iDEAL, etc.) erreichen oft nie zuverlaessig einen Browser-“Dankeschön”-Zustand. In diesem Fall senden Sie order_completed von Ihrem Backend, nachdem der Webhook des Zahlungsanbieters die Bestellung bestaetigt.

1. Gehen Sie im Dashboard zu Einstellungen → Sites, erweitern Sie API-Schluessel unter der Site und erstellen Sie einen Site-begrenzten Schluessel. Kopieren Sie ihn sofort (er wird nur einmal angezeigt).
2. POST an /api/event mit dem Schluessel als Bearer-Token. Der Body ist JSON. Beachten Sie, dass items ein JSON-kodierter String ist (ein Array serialisiert zu einem String), weil MetriXs alle Event-Props als Strings speichert:

{
  "n": "order_completed",
  "u": "https://yourdomain.com/thanks",
  "d": "yourdomain.com",
  "p": {
    "total": 49.99,
    "currency": "EUR",
    "items": "[{\"title\":\"T-shirt\",\"quantity\":2,\"price\":24.99}]"
  }
}

Entsprechendes curl:

curl -X POST https://app.metrixs.eu/api/event \
  -H "Authorization: Bearer mtx_live_yourapikey" \
  -H "Content-Type: text/plain" \
  -d '{"n":"order_completed","u":"https://yourdomain.com/thanks","d":"yourdomain.com","p":{"total":49.99,"currency":"EUR","items":"[{\"title\":\"T-shirt\",\"quantity\":2,\"price\":24.99}]"}}'

Anforderungen fuer den serverseitigen Pfad:

• Der API-Schluessel muss Site-begrenzt sein auf die Site, die das Event sendet (die d-Domain). Die API lehnt die Anfrage ab, wenn die Site des Schluessels nicht mit d uebereinstimmt.
• u (Seiten-URL) und d (Domain) sind erforderlich und muessen mit einer verifizierten Site auf Ihrem Konto uebereinstimmen.
• Content-Type ist text/plain (vermeidet ein CORS-Preflight auf dem Browser-Pfad; die API parst den Body als JSON ungeachtet).
• Das Browser-Bot-Erkennungs-Token wird uebersprungen fuer API-Schluessel-authentifizierte Anfragen, da ein Server keinen Browser-Fingerprint produzieren kann und der Schluessel bereits beweist, dass der Aufrufer das Backend des Site-Eigentuemers ist.
• Dieselbe pro-IP-Ratenlimitierung wie beim Browser-Pfad gilt weiterhin.

Was Sie im Dashboard bekommen

Sobald Commerce an ist und Events fliessen, zeigt das Dashboard der Site:

• Umsatz, Summe von total auf order_completed-Events (in Ihrer Anzeigewaehrung gezeigt; in EUR gespeichert).
• AOV, Umsatz / Anzahl order_completed-Events.
• Conv. rate, order_completed-Anzahl / eindeutige Besucher × 100.
• Conversion-Trichter, Besucher → checkout_started → payment_submitted → order_completed.
• Top-Produkte, Umsatz und Menge pro Produkttitel (aus items).
• Umsatz pro Quelle / Standort / Geraet, die Umsatz-Spalte erscheint auch in diesen Panels, sodass Sie Umsatz einer Kampagne oder einem Kanal zuordnen koennen.

Migration von Google Analytics 4

Wenn Sie bereits GA4-E-Commerce-Events ueber den dataLayer feuern, sind die Eigenschaftsformen aehnlich, aber die Event-Namen unterscheiden sich. Das Mindest-Mapping:

GA4-Event	MetriXs-Event
begin_checkout	checkout_started
add_payment_info	payment_submitted
purchase	order_completed

Das items-Array verwendet { title, quantity, price } statt GA4’s { item_name, quantity, price }, also benennen Sie item_name zu title um, wenn Sie Ihren bestehenden dataLayer-Push anpassen.