Werden Aufrufe vor dem Laden des Trackers verworfen?

Ja. window.xictraq existiert erst, nachdem der Tracker (script defer) ausgeführt wurde; einen Vorab-Puffer gibt es nicht. Rufen Sie die API deshalb defensiv auf (Guard auf window.xictraq) oder erst nach dem Load-Event.

Sende ich damit personenbezogene Daten?

Mit identify ja: Kundennummer, Name und Firma sind personenbezogene Daten, die Sitzung ist danach nicht mehr pseudonym. Die automatische Kundenerkennung liest Name und Firma bei erkannten Shops auch aus Profil- und Checkout-Feldern. Übergeben Sie manuell nur, was Sie für die Auswertung brauchen; E-Mail-Adressen und Telefonnummern gehören weder in identify noch in Event-Eigenschaften. Die Formular-Analyse misst Längen und Zeiten, keine Eingabeinhalte. Cookies setzt der Tracker in keinem Fall.

Brauche ich manuelle E-Commerce-Calls bei WooCommerce?

Für Warenkorb, Checkout und Bestellungen nicht: Bei WooCommerce, Shopify, Shopware, Magento, PrestaShop und über 20 weiteren Systemen erfasst der Tracker sie automatisch. Gutscheincode und Erstattungen übergeben Sie mit xictraq.revenue() und xictraq.refund(); alle übrigen Calls sind nur für Custom- oder Headless-Frontends nötig, die nicht automatisch erkannt werden.

Wie teste ich, ob Events ankommen?

Öffnen Sie die Netzwerk-Konsole des Browsers und filtern Sie auf /api/p — bei jedem API-Aufruf sehen Sie einen Beacon-Request. Im Dashboard erscheinen die Ereignisse anschließend im Analytics-Bereich. Hinweis: Auf localhost und 127.0.0.1 läuft der Tracker bewusst nicht.

Zählen Custom-Events gegen ein Limit?

Events zählen wie Seitenaufrufe gegen Ihr monatliches Pageview-Kontingent des Plans (z. B. Starter 100k, Business 1M). Ein separates Event-Limit gibt es nicht.

JS-Tracker-API

Das Standard-Snippet (data-site) erfasst Seitenaufrufe, Klicks, Web Vitals, Formulare, Medien, Heatmaps sowie die automatische E-Commerce- und Identitäts-Erkennung für über 25 Shop-Systeme bereits ohne eine Zeile Code. Die globale JavaScript-API window.xictraq ist für alles darüber hinaus: eigene Events, manuelles E-Commerce-Tracking in Custom- und Headless-Frontends, Nutzer-Identifikation, A/B-Tests und das Consent-Gate. Diese Seite dokumentiert jede Methode mit Signatur, Beispiel und Rückgabewert.

# Voraussetzung & Guard

Die JS-API steht bereit, sobald das normale Tracker-Snippet eingebunden ist — Sie brauchen kein zweites Script. Für die Standard-Fälle (Reichweite, Formulare, Medien, Heatmaps, Web Vitals und E-Commerce/Identity für über 25 Shop-Systeme) müssen Sie gar nichts programmieren; die API ist ausschließlich für manuelle und zusätzliche Fälle gedacht.

<script defer src="https://api.xictraq.com/t.js"
        data-site="YOUR_SITE_ID"></script>

Hinter dem First-Party-Proxy sieht das Snippet anders aus — die API nicht

Wer den Tracker über die eigene Domain ausliefert, bindet ihn als <script defer src="/t.js" data-site="…" data-api="/a"> ein. window.xictraq, alle hier dokumentierten Methoden und ihre Rückgabewerte bleiben identisch — nur die Zieladresse der Beacons wandert auf Ihre Domain. Eigene Aufrufe wie xictraq.event() oder xictraq.revenue() laufen damit ebenfalls über /a/ auf Ihrer Domain. Den geprüften nginx-Block für /t.js, /a/ und bei Session-Recording /rx.js, mit verborgenem HSTS von api.xictraq.com, überschriebenem X-Forwarded-For und 20 MB Anfragegröße für Aufzeichnungen, finden Sie in Erste Schritte.

Wann window.xictraq verfügbar ist — immer defensiv aufrufen

Der Tracker lädt mit script defer, daher existiert window.xictraq erst, nachdem das Snippet ausgeführt wurde. Einen Vorab-Puffer gibt es nicht: Aufrufe, die vor dem Laden abgesetzt werden, gehen verloren. Rufen Sie die API deshalb defensiv auf — nur, wenn window.xictraq existiert (oder erst nach dem Load-Event).

<script>
  // window.xictraq existiert erst, wenn der Tracker geladen ist.
  if (window.xictraq) {
    xictraq.event('newsletter_signup', { plan: 'pro' });
  }
</script>

Meistens brauchen Sie gar keinen Code

Für Reichweite, Formulare, Medien, Heatmaps, Web Vitals sowie E-Commerce bei über 25 gängigen Shop-Systemen (WooCommerce, Shopify, Shopware, Magento, PrestaShop u. v. m.) läuft alles automatisch, die Nutzer-Identifikation in Shopware, Shopify, WooCommerce/WordPress, PrestaShop, Drupal, Joomla, TYPO3 und BigCommerce. Greifen Sie zur JS-API nur bei eigenen Events, für Gutscheincode und Erstattungen, für die Identifikation in anderen Systemen oder bei Custom-/Headless-Frontends.

# Custom Events

Eigene Events senden (event)

xictraq.event(name, props?) meldet ein beliebiges Ereignis. name ist ein String, props ein optionales Objekt mit frei wählbaren Eigenschaften. So erfassen Sie Interaktionen, die kein Standard-Feature abdeckt — etwa Newsletter-Anmeldungen, Downloads oder CTA-Klicks.

// Einfaches Event ohne Eigenschaften
xictraq.event('newsletter_signup');

// Event mit Eigenschaften (beliebiges Objekt)
xictraq.event('newsletter_signup', { plan: 'pro', source: 'footer' });

// Weitere Beispiele
xictraq.event('download', { file: 'preisliste.pdf' });
xictraq.event('video_cta_click', { position: 'hero' });

# Nutzer-Identifikation

Session mit Kunden-/Shop-ID verknüpfen (identify)

xictraq.identify(userId, traits?) verknüpft die zunächst pseudonyme Sitzung (Tageskennung) mit einer Kunden- oder Shop-ID. Kundennummer und Merkmale sind personenbezogene Daten; übergeben Sie nur, was Sie für die Auswertung brauchen. userId ist Ihre interne ID oder Kundennummer, traits ein optionales Objekt mit Merkmalen wie Typ oder Gruppe. Damit erscheinen wiederkehrende Kunden tagesübergreifend als identifizierte Nutzer im Dashboard.

// Nur die ID
xictraq.identify('cust_10492');

// Mit zusätzlichen Merkmalen (keine E-Mail-Adressen)
xictraq.identify('cust_10492', { type: 'b2b', group: 'wiederkehrend' });

Automatische Erkennung ohne JS-Call

Für gängige Shop-Systeme erkennt der Tracker eingeloggte Kunden automatisch. Ohne Shop-Anbindung genügt eine der drei Konventionen unten — der manuelle identify-Aufruf ist dann nicht nötig.

<!-- 1) Globale Variable -->
<script>window.xictraqUser = { id: 'cust_10492', type: 'b2b' };</script>

<!-- 2) Meta-Tag im <head> -->
<meta name="xictraq:user-id" content="cust_10492">

<!-- 3) Attribut an einem beliebigen Element -->
<body data-user-id="cust_10492">

Personenbezogene Daten sparsam übergeben

Mit identify endet die Pseudonymität der Sitzung: Kundennummer, Name und Firma sind personenbezogene Daten. Die automatische Erkennung übernimmt Name und Firma, wo Ihr Shop sie anzeigt; manuell übergeben Sie nur, was Sie für die Auswertung brauchen. E-Mail-Adressen und Telefonnummern gehören weder in identify noch in Event-Eigenschaften; Merkmale mit einer E-Mail-Adresse verwirft der Server, eine Kennung (userId) in Form einer E-Mail-Adresse samt dem ganzen Aufruf; nutzen Sie dafür die Kundennummer. Die Verknüpfung selbst wird unabhängig vom Tarif spätestens 365 Tage nach dem letzten Besuch gelöscht.

# E-Commerce manuell

Für gängige Shops läuft das automatisch

Für WooCommerce, Shopify, Shopware, Magento, PrestaShop und über 20 weitere Systeme erfasst der Tracker Warenkorb, Checkout und Bestellungen ohne Code. Gutscheincode und Erstattungen übergeben Sie auch dort mit xictraq.revenue() und xictraq.refund(); die übrigen Methoden brauchen Sie nur für Custom- oder Headless-Frontends, die nicht automatisch erkannt werden.

Bestellung / Umsatz (revenue)

xictraq.revenue(amount, currency, orderId, extras?) meldet einen abgeschlossenen Kauf. amount ist der Bruttobetrag als Zahl, currency ein ISO-Währungscode, orderId Ihre Bestellnummer. extras ist ein optionales Objekt mit Steuer, Versand und Gutschein-Code.

xictraq.revenue(129.90, 'EUR', 'ORDER-2026-8841', {
  tax: 20.75,
  shipping: 4.95,
  coupon: 'WELCOME10'
});

Produktansicht (product)

xictraq.product('view', props) meldet, dass ein Besucher ein Produkt angesehen hat. props enthält die Felder id, name, price und category.

xictraq.product('view', {
  id: 'SKU-4471',
  name: 'Laufschuh Pro',
  price: 119.00,
  category: 'Schuhe/Running'
});

Warenkorb (cart)

xictraq.cart('add' oder 'remove', props) meldet eine Warenkorb-Änderung. Der erste Parameter ist die Aktion, props enthält id, name, price und quantity.

// In den Warenkorb legen
xictraq.cart('add', { id: 'SKU-4471', name: 'Laufschuh Pro', price: 119.00, quantity: 1 });

// Aus dem Warenkorb entfernen
xictraq.cart('remove', { id: 'SKU-4471', name: 'Laufschuh Pro', price: 119.00, quantity: 1 });

Checkout-Schritt (checkout)

xictraq.checkout(step, meta?) markiert einen Schritt im Checkout-Funnel. step ist eine Zahl oder ein Name, meta ein optionales Objekt mit Zusatzinfos zum Schritt.

xictraq.checkout(1, { step_name: 'Adresse' });
xictraq.checkout(2, { step_name: 'Versand' });
xictraq.checkout('payment');

Rückerstattung (refund)

xictraq.refund(orderId, amount, currency) meldet eine Erstattung zu einer früheren Bestellung. Alle drei Parameter sind erforderlich: die ursprüngliche Bestellnummer, der erstattete Betrag und der Währungscode.

xictraq.refund('ORDER-2026-8841', 129.90, 'EUR');

Gescheiterte Zahlung (paymentFailed)

xictraq.paymentFailed(orderId, amount, currency, extras) meldet eine Zahlung, die beim Zahlungsanbieter abgelehnt oder abgebrochen wurde. Den Abbruch kennt nur der Shop, darum gibt es keine automatische Erkennung. Die Zahlungsart steht in extras.payment_method; fehlt sie, liest der Tracker sie wie beim Kauf aus der Seite. Die Auswertung Zahlung und Versand zeigt daraus je Zahlungsart den Anteil gescheiterter Versuche und wie viele Sitzungen danach doch gekauft haben.

xictraq.paymentFailed('ORDER-2026-8842', 89.00, 'EUR', { payment_method: 'Kreditkarte' });

# A/B-Testing

Variante zuweisen (experiment)

xictraq.experiment(name) weist dem Besucher eine A/B-Variante zu und gibt ein Promise zurück, das mit der Variante (z. B. 'A' oder 'B') aufgelöst wird. Die Zuweisung hängt am cookielosen Sitzungsschlüssel aus IP-Adresse und Tagesdatum: innerhalb eines Tages sieht derselbe Besucher dieselbe Variante, am nächsten Tag oder nach einem Wechsel der IP-Adresse kann er neu zugewiesen werden. Läuft kein Experiment dieses Namens, wird das Promise mit null aufgelöst.

xictraq.experiment('pricing_headline').then(function (variant) {
  if (variant === 'B') {
    document.querySelector('#headline').textContent = 'Neu: 30 Tage gratis';
  }
});

Conversion melden (convert)

xictraq.convert(name) meldet, dass der Besucher das Ziel des Experiments erreicht hat — etwa einen Kauf oder eine Anmeldung. XICTRAQ berechnet daraus Conversion-Rate, Uplift und statistische Signifikanz je Variante.

// z. B. nach Klick auf den CTA oder erfolgreichem Kauf
xictraq.convert('pricing_headline');

# Komplette API-Referenz

Alle Methoden von window.xictraq auf einen Blick. Optionale Parameter sind mit einem Fragezeichen markiert.

Methode	Parameter	Zweck
`xictraq.event`	`name (String), props? (Objekt)`	Eigenes Event auslösen
`xictraq.identify`	`userId (String), traits? (Objekt)`	Session mit Kunden-/Shop-ID verknüpfen (personenbezogen)
`xictraq.revenue`	`amount (Zahl), currency (String), orderId (String), extras? (tax, shipping, coupon)`	Bestellung / Umsatz erfassen
`xictraq.product`	`'view', props (id, name, price, category)`	Produktansicht
`xictraq.cart`	`'add' \| 'remove', props (id, name, price, quantity)`	Warenkorb-Änderung
`xictraq.checkout`	`step (Zahl/Name), meta? (Objekt)`	Checkout-Schritt
`xictraq.refund`	`orderId (String), amount (Zahl), currency (String)`	Rückerstattung
`xictraq.paymentFailed`	`orderId? (String), amount? (Zahl), currency? (String), extras? (payment_method)`	Gescheiterte Zahlung
`xictraq.experiment`	`name (String) → Promise(variant)`	A/B-Variante zuweisen (Promise)
`xictraq.convert`	`name (String)`	A/B-Conversion melden
`xictraq.consent`	`'granted' \| 'denied'`	Consent-Gate (steuert Session-Recording)
`xictraq.record`	`'start' \| 'stop'`	Session-Recording auf dieser Seite ein- oder ausschalten (Einwilligung bleibt nötig)

Häufige Fragen

Nein. Das Standard-Snippet erfasst Seitenaufrufe, Klicks, Formulare, Medien, Web Vitals, Heatmaps sowie E-Commerce und Identity für über 25 Shop-Systeme automatisch. Die JS-API brauchen Sie nur für eigene Events, für Gutscheincode und Erstattungen oder für Custom-/Headless-Frontends.