e-Commerce Tracking

Diese Anleitung beschreibt, wie du das E-Commerce-Tracking von Trackboxx manuell in einen Shop integrierst – unabhängig davon, ob du ein Custom-System, Shopify, Shopware, Magento oder einen anderen Shop einsetzt. Für WooCommerce steht ein offizielles Plugin bereit, das alle hier beschriebenen Events automatisch auslöst.

Grundlogik: Was bedeutet trackboxx('Purchase', [...])?

Bevor es an die einzelnen Events geht, ein wichtiger Punkt zum Verständnis – dieser Punkt wird erfahrungsgemäß am häufigsten falsch interpretiert:

Wichtig: trackboxx('Purchase', [...]) ist kein einzelnes Event, sondern der generische Aufruf für alle E-Commerce-Interaktionen. Welches Event tatsächlich getrackt wird, bestimmt das erste Objekt im Array über seinen type:

• { type: 'ViewProduct' } – Produktdetailseite
• { type: 'AddToCart' } – Produkt in den Warenkorb gelegt
• { type: 'ViewCart' } – Warenkorbseite angesehen
• { type: 'order' } – Bestellung abgeschlossen

Das 'Purchase' im Funktionsaufruf bezeichnet lediglich die Aktionskategorie „E-Commerce“ und bleibt immer gleich – egal ob du eine Produktansicht, einen Add-to-Cart oder einen tatsächlichen Kauf trackst.

Die vier E-Commerce-Events im Überblick

1. ViewProduct – Produktdetailseite

Auslösen: Beim Aufruf einer Produktdetailseite.
Minimaldaten: Produktname und Einzelpreis.

<script>
trackboxx('Purchase', [
  { type: 'ViewProduct' },
  { type: 'product', name: '%%PRODUCT_NAME%%', price: 99.90 }
]);
</script>Code-Sprache: HTML, XML (xml)

Hinweise:

• price = Einzelpreis des Produkts (numerisch, Punkt als Dezimaltrenner).
• Optionale Zusatzfelder: sku, category.
• Bei Varianten oder Bundles: den kompletten Variantennamen inkl. Attribute übergeben (z. B. „T-Shirt – rot, L“), damit Reports konsistent aggregiert werden.

2. AddToCart – Produkt in den Warenkorb gelegt

Auslösen: Nach erfolgreichem „In den Warenkorb“-Vorgang – nicht blind beim Klick.
Minimaldaten: Produktname und Einzelpreis.

<script>
trackboxx('Purchase', [
  { type: 'AddToCart' },
  { type: 'product', name: '%%PRODUCT_NAME%%', price: 19.99 }
]);
</script>Code-Sprache: HTML, XML (xml)

Hinweise zum Timing – je nach Shop-Typ:

• Custom Shops und AJAX-Warenkörbe: Event im Success-Callback der Add-to-Cart-Aktion feuern, nicht im Click-Handler. So wird kein Tracking-Event erzeugt, wenn der Artikel aufgrund von Bestandsprüfung, Validierung oder Netzwerkfehlern gar nicht im Warenkorb landet.
• Serverseitige Shops mit Redirect: Event auf der Folgeseite nach erfolgreichem Add einmalig auslösen.
• Einfache Button-Klick-Integrationen: erlaubt, aber nur, wenn sichergestellt ist, dass der Klick tatsächlich zu einem erfolgreichen Add führt (z. B. Button-Disabled-Check bei ausverkauften Produkten).
• Deduplizierung: AddToCart nur einmal pro Aktion senden – keine Dopplung bei Reload oder Zurück-Navigation.

3. ViewCart – Warenkorbseite

Auslösen: Beim Aufruf der Warenkorbseite.
Minimaldaten: Cart-Summe (amount). Optional: alle enthaltenen Produkte als separate Objekte.

<script>
trackboxx('Purchase', [
  { type: 'ViewCart' },
  { type: 'cart', amount: 149.70 },
  { type: 'product', name: 'Produkt A', price: 99.90 },
  { type: 'product', name: 'Produkt B', price: 49.80 }
]);
</script>Code-Sprache: HTML, XML (xml)

Hinweise:

• amount = Gesamtsumme des Warenkorbs. Standard: Netto (entspricht dem Verhalten des offiziellen WooCommerce-Plugins).
• Wenn dein Shop mit Bruttopreisen arbeitet, sind Bruttowerte ebenfalls erlaubt – entscheidend ist Konsistenz innerhalb eines Events: cart.amount und alle product.price-Werte müssen auf derselben Basis (alle netto oder alle brutto) berechnet sein.
• Pro Warenkorbposition ein eigenes product-Objekt anhängen.
• Der price pro Produkt entspricht hier der Positionssumme (Einzelpreis × Menge) – siehe Abschnitt „Preislogik & Quantity“.

4. Purchase – Bestellabschluss (Danke-Seite)

Auslösen: Auf der Bestellbestätigungsseite nach erfolgreicher Zahlung – genau einmal pro Bestellung.
Minimaldaten: Order-ID, Gesamtbetrag, alle gekauften Produkte.

<script>
trackboxx('Purchase', [
  { type: 'order', id: 'ORDER_ID', total: 149.70 },
  { type: 'product', name: 'Produkt A', price: 99.90 },
  { type: 'product', name: 'Produkt B', price: 49.80 }
]);
</script>Code-Sprache: HTML, XML (xml)

Optional – mit Gutschein: Pro eingesetztem Gutschein ein zusätzliches coupon-Objekt anhängen.

<script>
trackboxx('Purchase', [
  { type: 'order', id: '12345', total: 149.70 },
  { type: 'coupon', name: 'SUMMER10', discount: 10.00 },
  { type: 'product', name: 'Produkt A', price: 99.90 },
  { type: 'product', name: 'Produkt B', price: 49.80 }
]);
</script>Code-Sprache: HTML, XML (xml)

Hinweise:

• Beim Purchase-Event gibt es keinen vorangestellten Event-Marker wie bei ViewProduct oder AddToCart – das order-Objekt identifiziert den Event selbst.
• order.id = eindeutige Bestell-ID aus dem Shop-System.
• order.total = Gesamtwert der Bestellung (Brutto-Endbetrag inkl. Versand und Steuern wird empfohlen, muss aber zur Konsistenz mit den product.price-Werten passen).
• product.price = Positionssumme (Einzelpreis × Menge), nicht Einzelpreis.
• Gegen mehrfaches Feuern absichern (Reload-Schutz), z. B. über serverseitiges Flag oder Session-Marker.

Preislogik & Quantity

Trackboxx verwendet kein separates quantity-Feld. Mengen werden implizit über den Preis abgebildet. Diese Regel ist verbindlich und sollte in jeder Integration gleich umgesetzt werden:

Beispiel: Drei identische Artikel à 19,99 € im Warenkorb werden bei ViewCart und Purchase als ein product-Objekt mit price: 59.97 gesendet – nicht als drei separate Objekte und ohne quantity-Feld.

Reihenfolge der Objekte im Array

Für eine saubere, konsistente Integration empfehlen wir folgende Reihenfolge der Objekte:

1. Event-Marker bzw. order-Objekt (ViewProduct / AddToCart / ViewCart / order)
2. cart-Objekt (nur bei ViewCart)
3. coupon-Objekte (nur bei Purchase, falls vorhanden)
4. product-Objekte

Best Practices

• Deduplizierung: Jedes Event nur einmal pro tatsächlicher Aktion senden – kein Doppeltracking bei Reload, Zurück-Navigation oder AJAX-Retries.
• Timing: ViewProduct und ViewCart beim Seitenaufbau feuern. AddToCart nach bestätigtem Hinzufügen. Purchase einmalig auf der Danke-Seite.
• Preise & Beträge: Als Number übergeben (kein String), mit Punkt als Dezimaltrenner (z. B. 19.99 – nicht "19,99").
• Konsistenz: Netto oder brutto ist eine Entscheidung pro Shop – aber dann durchgängig für cart.amount, product.price und order.total.
• Datenschutz: Niemals personenbezogene Daten übergeben – keine E-Mail-Adressen, Namen, Kundennummern oder Adressen. Consent respektieren.

Schnell-Checkliste je Shop-System

• WooCommerce: Nutze das offizielle Trackboxx-Plugin. Es löst alle vier Events (ViewProduct, AddToCart, ViewCart, Purchase) automatisch aus – keine manuelle Integration nötig.
• Custom Shops: Serverseitig Produktname, Preis und Summe als Variablen in das jeweilige Inline-Script einsetzen.
• Shopify: Snippets in die Templates einbauen (product.liquid, cart.liquid, Checkout-Thank-You-Page). Für AddToCart am AJAX-Success-Callback andocken.
• Shopware / Magento: An die entsprechenden Events bzw. Hooks im Theme oder Plugin hängen – Produktseite, Warenkorbseite, Add-to-Cart-Event, Order-Complete-Event.

Referenz: Minimalvarianten

ViewProduct (minimal)

trackboxx('Purchase', [
  { type: 'ViewProduct' },
  { type: 'product', name: 'Product Name 1', price: 19.99 }
]);Code-Sprache: JavaScript (javascript)

AddToCart (minimal)

trackboxx('Purchase', [
  { type: 'AddToCart' },
  { type: 'product', name: 'Product Name 1', price: 19.99 }
]);Code-Sprache: JavaScript (javascript)

ViewCart (minimal)

trackboxx('Purchase', [
  { type: 'ViewCart' },
  { type: 'cart', amount: 19.99 }
]);Code-Sprache: JavaScript (javascript)

Purchase (minimal)

trackboxx('Purchase', [
  { type: 'order', id: 'ORDER_ID', total: 19.99 },
  { type: 'product', name: 'Product Name 1', price: 19.99 }
]);Code-Sprache: JavaScript (javascript)

Kurzüberblick: Die wichtigsten Regeln

• trackboxx('Purchase', [...]) ist ein generischer E-Commerce-Call, kein Event.
• Der Eventtyp steckt im Payload (type-Feld des ersten Objekts), nicht im Funktionsaufruf.
• AddToCart nach erfolgreichem Add feuern – nicht blind beim Klick.
• cart.amount im Standard als Netto-Wert; Brutto erlaubt, aber konsistent innerhalb des Events.
• price = Einzelpreis bei ViewProduct / AddToCart, Positionssumme bei ViewCart / Purchase.
• Kein separates quantity-Feld – Mengen über den Preis abbilden.
• Purchase-Event basiert auf { type: 'order' } ohne vorangestellten Event-Marker.
• Preise als Number mit Punkt-Dezimaltrenner, niemals als String.
• Keine personenbezogenen Daten im Payload.