Standard Integration

Verbinden Sie usertrax mit jeder Art von Website, um Conversions automatisch zu tracken und Ihre Marketing-Kampagnen zu optimieren.

Installation

1. Tracking-Script einbinden

Fügen Sie das usertrax Tracking-Script in den <head> Bereich Ihrer HTML-Seiten ein:

<script src="https://usertrax.io/cvs.js" data-key="IHR_API_SCHLÜSSEL"></script>

Wichtig: Ersetzen Sie IHR_API_SCHLÜSSEL mit Ihrem tatsächlichen API-Schlüssel aus dem usertrax Dashboard.

2. Script-Position

Das Script sollte möglichst früh im <head> Bereich geladen werden, um alle Conversions zu erfassen:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Ihre Website</title>

    <!-- usertrax Tracking-Script -->
    <script
      src="https://usertrax.io/cvs.js"
      data-key="IHR_API_SCHLÜSSEL"
    ></script>
  </head>
  <body>
    <!-- Ihre Website-Inhalte -->
  </body>
</html>

Konfiguration

Erweiterte Konfiguration

Sie können das Tracking-Verhalten anpassen, indem Sie die usertraxConfig vor dem Laden des Scripts definieren:

<script>
  window.usertraxConfig = {
    endpoint: "https://api.usertrax.io/api/events",
    crossDomainParamName: "uxs",
    crossDomainDomains: [],
    sessionTimeout: 24 * 60 * 60 * 1000,
    respectDoNotTrack: false,
    // Ads/Marketing-Weiterleitung (standardmäßig deaktiviert)
    ads: false,
    ga4: false,
    tagManager: false,
    facebook: false,
    posthog: false,
    // Tracking auf bestimmten Pfaden aus (SPA-aware; Session-ID bleibt erhalten)
    disableOnPages: ["/form/*", "/checkout"],
  };
</script>
<script src="https://usertrax.io/cvs.js" data-key="IHR_API_SCHLÜSSEL"></script>

disableOnPages unterstützt exakte Pfade, *-Globs (z. B. /form/*), RegExp und Funktionen (pathname, location) => boolean. Auf matchenden Routen werden keine API-Requests gesendet (Session, Conversions, Ads-Forwarding). Die Session-ID in localStorage bleibt bestehen. Bei SPA-Navigation von einer deaktivierten auf eine aktive Route wird die Session nachgeholt.

Events werden über das type-Feld verteilt:

`type`	Zweck
`session`	Session-Init + A/B-Config (beim Seitenload)
`conversion`	Conversions via `usertrax.push` oder Klicks

Legacy-Endpunkte /api/tracker/conversion und /api/tracker/session bleiben für ältere gecachte Scripts verfügbar. /api/tracker/events ist ein Alias für /api/events.

First-Party-Proxy (Adblocker umgehen)

Um Script und Events über Ihre eigene Domain zu routen, siehe Proxy-Anleitungen.

Conversion Tracking

1. Automatisches Tracking

Das Script erfasst beim Seitenload automatisch:

Sessions: Benutzer-Sessions werden erstellt und an die API gesendet
A/B-Tests: Aktive Tests werden geladen und Varianten angewendet
Tracking-Parameter: UTM-Parameter, Google Ads, Facebook, Microsoft Ads IDs

2. Manuelles Conversion Tracking

Verwenden Sie die usertrax.push() Funktion für benutzerdefinierte Conversions:

// Einfache Conversion
usertrax.push({
  event: "purchase",
  total: 99.99,
  currency: "EUR",
});

// Detaillierte Conversion mit Metadaten
usertrax.push({
  event: "form_submit",
  id: "lead_12345",
  label: "Newsletter Anmeldung",
  total: 0,
  currency: "EUR",
  metadata: {
    form_type: "newsletter",
    page: "homepage",
  },
});

3. HTML-Attribute für automatisches Tracking

Verwenden Sie data-usertrax Attribute für automatisches Event-Tracking:

<!-- Einfaches Event -->
<button data-usertrax="button_click">Klick mich</button>

<!-- Event mit Wert -->
<button
  data-usertrax="purchase"
  data-usertrax-total="49.99"
  data-usertrax-currency="EUR"
>
  Kaufen
</button>

<!-- Event mit Metadaten -->
<form data-usertrax="form_submit" data-usertrax-label="Kontaktformular">
  <!-- Formular-Inhalte -->
</form>

A/B Testing Integration

1. HTML-Elemente für A/B Tests

Verwenden Sie spezielle Attribute für A/B Testing:

<!-- Variante A -->
<div
  data-usertrax-ab-test-group="headline_test"
  data-usertrax-ab-test-variant="A"
>
  <h1>Willkommen bei uns!</h1>
</div>

<!-- Variante B -->
<div
  data-usertrax-ab-test-group="headline_test"
  data-usertrax-ab-test-variant="B"
>
  <h1>Entdecken Sie unsere Angebote!</h1>
</div>

<!-- Fallback (wird angezeigt, wenn kein Test aktiv ist) -->
<div data-usertrax-ab-test-group="headline_test" data-usertrax-ab-test-fallback>
  <h1>Willkommen!</h1>
</div>

2. JavaScript für A/B Tests

// Aktuelle Variante abrufen
const variant = usertrax.getVariant("headline_test");

// Alle A/B Test-Zuweisungen abrufen
const assignments = usertrax.getAssignments();

// Element-Sichtbarkeit manuell anwenden
usertrax.applyElementVisibility();

Cross-Domain Tracking

Konfiguration

Aktivieren Sie Cross-Domain Tracking für mehrere Domains:

window.usertraxConfig = {
  crossDomainParamName: "uxs",
  crossDomainDomains: [
    "shop.example.com",
    "blog.example.com",
    "landing.example.com",
  ],
};

Funktionsweise

Session-ID wird in URLs eingefügt: Beim Klick auf externe Links wird die Session-ID automatisch als URL-Parameter hinzugefügt
Automatische Erkennung: Das Script erkennt die Session-ID auf der Zielseite
Nahtlose Verfolgung: Conversions werden der ursprünglichen Session zugeordnet

Tracking-Parameter

Automatisch erfasste Parameter

Das Script erfasst automatisch folgende Tracking-Parameter:

Google Ads: gclid, gclsrc, dclid
Facebook Ads: fbclid, fbc, fbp
Microsoft Ads: msclkid
TikTok Ads: ttclid
UTM-Parameter: utm_source, utm_medium, utm_campaign, etc.

Parameter-Speicherung

Parameter werden automatisch im localStorage gespeichert und bei Conversions mitgesendet:

// Parameter werden automatisch erfasst und gespeichert
// https://ihre-website.com/?gclid=abc123&utm_source=google

// Bei der nächsten Conversion werden diese Parameter automatisch mitgesendet
usertrax.push({
  event: "purchase",
  total: 99.99,
  // gclid und utm_source werden automatisch hinzugefügt
});

Beispiele

E-Commerce Conversion

// Produktansicht
usertrax.push({
  event: "view_item",
  id: "product_123",
  label: "iPhone 15 Pro",
  total: 1199.0,
  currency: "EUR",
  metadata: {
    category: "Smartphones",
    brand: "Apple",
  },
});

// Warenkorb hinzufügen
usertrax.push({
  event: "add_to_cart",
  id: "product_123",
  label: "iPhone 15 Pro",
  total: 1199.0,
  currency: "EUR",
});

// Kauf abschließen
usertrax.push({
  event: "purchase",
  id: "order_45678",
  label: "iPhone 15 Pro",
  total: 1199.0,
  currency: "EUR",
  metadata: {
    order_id: "45678",
    payment_method: "credit_card",
  },
});

Lead-Generierung

<!-- Kontaktformular -->
<form
  id="contact-form"
  data-usertrax="form_submit"
  data-usertrax-label="Kontaktformular"
>
  <input type="text" name="name" placeholder="Name" required />
  <input type="email" name="email" placeholder="E-Mail" required />
  <button type="submit">Absenden</button>
</form>

<script>
  document
    .getElementById("contact-form")
    .addEventListener("submit", function (e) {
      // Formular wird automatisch getrackt durch data-usertrax Attribute

      // Zusätzliche Metadaten hinzufügen
      usertrax.push({
        event: "lead_generated",
        label: "Kontaktformular",
        metadata: {
          form_type: "contact",
          page: "kontakt",
        },
      });
    });
</script>