Konfiguration & API

Erweiterte Konfiguration

Tracker-Konfiguration

window.usertraxConfig = {
  // API-Endpunkt (einheitlich für alle Events)
  endpoint: "https://api.usertrax.io/api/events",

  // Cross-Domain-Einstellungen
  crossDomainParamName: "uxs",
  crossDomainDomains: ["checkout.example.com"],

  // Session & Privacy
  sessionTimeout: 24 * 60 * 60 * 1000, // 24 Stunden Inaktivität
  respectDoNotTrack: false,

  // Tracking auf ausgewählten Pfaden aus (SPA-aware)
  disableOnPages: ["/form/*"],

  // Ads-/Marketing-Weiterleitung (alles standardmäßig aus)
  ads: false, // Legacy: aktiviert ga4 + tagManager + facebook
  ga4: false,
  tagManager: false,
  facebook: false,
  posthog: false,
};

Setze window.usertraxConfig vor dem Laden des Tracker-Scripts.

Konfigurationsoptionen

Option	Typ	Standard	Beschreibung
`endpoint`	string	`https://api.usertrax.io/api/events`	Einheitliche Ingest-URL für alle Tracker-Events
`crossDomainParamName`	string	`"uxs"`	URL-Parameter-Name für die Session-ID
`crossDomainDomains`	array	`[]`	Domains für Cross-Domain-Tracking (`[]` = alle)
`sessionTimeout`	number	`86400000` (24h)	Session-TTL in Millisekunden (Inaktivität)
`respectDoNotTrack`	boolean	`false`	Bei `true`: Tracking stoppt, wenn Browser-DNT gesetzt ist
`disableOnPages`	array	`[]`	Pfade ohne Tracking (exakte Strings, `*`-Globs, `RegExp` oder `(pathname, location) => boolean`; SPA-aware). Session-ID in `localStorage` bleibt erhalten
`ads`	boolean	`false`	Legacy-Kurzschlüssel: aktiviert `ga4`, `tagManager` und `facebook` gemeinsam
`ga4`	boolean	`false`	Conversions an `gtag` (GA4) weiterleiten
`tagManager`	boolean	`false`	Conversions an `dataLayer` (GTM) weiterleiten
`facebook`	boolean	`false`	Conversions an `fbq` (Meta Pixel) weiterleiten
`posthog`	boolean	`false`	Events/`identify` an `window.posthog` weiterleiten

Details zu Ads-Weiterleitung und Enhanced Conversions: Ads & Enhanced Conversions.

Fehlerbehandlung und Debugging

Konfiguration und Session prüfen

// Aktuelle Konfiguration
console.log("Config:", window.usertraxConfig);

// Session-ID (localStorage)
console.log("Session ID:", localStorage.getItem("uxs_id"));
console.log("Last activity:", localStorage.getItem("uxs_last"));

Es gibt keinen debugMode-Schalter am Haupt-Tracker. Zum Debuggen Network-Tab (/api/events) und die Werte oben nutzen.

Häufige Probleme

Fehlender Auth-Key: Stellen Sie sicher, dass das data-key-Attribut im Script-Tag gesetzt ist
CORS-Fehler: Überprüfen Sie, ob API-Endpunkte zugänglich sind
Parameter nicht erfasst: Überprüfen Sie URL-Format und Parameternamen
Session wird nicht beibehalten: Überprüfen Sie, ob localStorage aktiviert ist
Keine Ads-Weiterleitung: Flags (ga4 / tagManager / facebook / ads) sind standardmäßig false

Best Practices

1. Konsistente Event-Benennung

// Verwenden Sie konsistente, beschreibende Event-Namen
usertrax.push({ event: "product_purchase" });
usertrax.push({ event: "newsletter_signup" });
usertrax.push({ event: "free_trial_start" });

2. Aussagekräftige Metadaten

// Relevanten Kontext einbinden
usertrax.push({
  event: "purchase",
  total: 99.99,
  metadata: {
    product_category: "electronics",
    product_brand: "Apple",
    checkout_method: "credit_card",
    user_segment: "premium",
  },
});

3. Korrekte Währungsbehandlung

// Währung für monetäre Events immer angeben
usertrax.push({
  event: "purchase",
  total: 99.99,
  currency: "EUR", // Explizite Währung
});

4. Nutzerdaten-Datenschutz

// Nur notwendige Nutzerdaten einbinden
usertrax.push({
  event: "signup",
  user_data: {
    email: "user@example.com", // Nur wesentliche Daten
    // Vermeiden Sie sensible Informationen wie Passwörter
  },
});

API-Referenz

usertrax.push()

usertrax.push(eventObject);

Parameter:

eventObject (object): Event-Daten mit beliebigen unterstützten Parametern

Rückgabewert: void

Siehe Events & Parameter für alle Objektschlüssel.

usertrax.identify()

usertrax.identify(distinctId, traits);

Parameter:

distinctId (string): Stabile externe Nutzer-ID (z. B. Datenbank-Primary-Key)
traits (object, optional): Personen-Eigenschaften; kanonische Schlüssel landen in user_data, andere nur in meta_data.$usertrax_identify

Rückgabewert: void

Details unter Nutzer-Identifikation.

window.usertrax.getVariant()

window.usertrax.getVariant(testKey);

Parameter:

testKey (string): A/B-Test-Identifier

Rückgabewert: string - Aktueller Varianten-Schlüssel oder null

window.usertrax.getAssignments()

window.usertrax.getAssignments();

Rückgabewert: object - Alle aktuellen A/B-Test-Zuweisungen

Mehr dazu in der A/B-Testing-Dokumentation.