Nutzer-Identifikation

Verknüpft den aktuellen Browser mit einem bekannten Nutzer (ähnlich wie PostHog identify). Einmal nach Login oder Registrierung aufrufen — jedes spätere push() enthält automatisch den Person-Kontext.

Bevorzuge usertrax.identify() als einzigen Aufruf: Wenn das Feedback-Widget auf derselben Seite läuft, setzt derselbe Call die Identität dort ebenfalls (E-Mail-Feld ausblenden, Metadaten). Die Identität liegt in localStorage (usertrax_identify) — das Widget übernimmt sie auch, wenn es nach dem Tracker lädt.

Web (Script-Tag)

// Nach dem Login
usertrax.identify("user_xyz", {
  email: "jane@example.com",
  plan: "team",
  seats: 5,
});

// Spätere Conversions erben user_data + Meta-Snapshot
usertrax.push({ event: "purchase", total: 49.99, currency: "EUR" });

NPM (ESM)

tracker.identify("user_xyz", {
  email: "jane@example.com",
  plan: "team",
});

Funktionsweise

Persistenz — Wird in localStorage (usertrax_identify) gespeichert und über Seitenaufrufe und Sessions hinweg wiederverwendet.
user_data-Merge — Kanonische Trait-Schlüssel (email, phone, phone_number, first_name, last_name, name, customer_id, address) werden in user_data jeder Conversion gemerged. Die Distinct-ID wird zu customer_id, wenn du keine explizit setzt. Felder in einem einzelnen push({ user_data: … }) überschreiben Traits aus identify.
Vollständiger Trait-Snapshot — Alle Traits (inkl. benutzerdefinierter Keys wie plan oder seats) gehen bei jeder Conversion unter meta_data.$usertrax_identify mit:

{
  "distinct_id": "user_xyz",
  "traits": { "email": "jane@example.com", "plan": "team", "seats": 5 }
}

PostHog — Wenn PostHog geladen ist und usertraxConfig.posthog nicht false ist, ruft identify zusätzlich posthog.identify(distinctId, traits) auf.
Feedback-Widget — Feuert usertrax:identify, damit ein geladenes Feedback-Widget dieselbe Identität übernimmt (hydriert beim Start auch aus localStorage).

Unterstützte Trait-Schlüssel für `user_data`

Trait-Schlüssel	In `user_data`
`email`	Ja
`phone`	Ja
`phone_number`	Ja
`first_name`	Ja
`last_name`	Ja
`name`	Ja
`customer_id`	Ja
`address`	Ja
Alle anderen	nur `meta_data`

Nutze setUserData(), wenn du nur Google Enhanced Conversions mit Hashing brauchst, ohne stabile Distinct-ID — siehe Ads & Enhanced Conversions. Nutze identify(), wenn eine persistente Person-ID und Traits auf allen Events mitgehen sollen.

Visitor-Profile (`uxv_id`)

Der Tracker speichert zusätzlich eine dauerhafte Visitor-ID in localStorage unter uxv_id (unabhängig von Session-Timeout / uxs_id) und sendet sie als visitor_id bei Session- und Conversion-Events. So können wiederkehrende Besucher und identifizierte Nutzer im Dashboard als ein Profil erscheinen.

Profile entstehen erst bei Identifikation

Eine visitor_id allein legt kein Profil an. Erst wenn über identify() eine email oder customer_id mitkommt, wird ein Profil erzeugt. Anonyme Besucher erscheinen also nicht in der Profil-Liste.

Die Vorgeschichte geht dabei nicht verloren: Die visitor_id wird auf jeder Session gespeichert, und sobald sich jemand identifiziert, werden dessen frühere anonyme Sessions und Conversions dem neuen Profil nachträglich zugeordnet.

Der Hintergrund: Ohne diese Regel bekäme jeder Browser ein Profil — und dort, wo localStorage blockiert ist, sogar eines pro Seitenaufruf. Das wären massenhaft Profile mit genau einer Session und ohne jede Identität. Für die reine Session-Auswertung ist die Sessions-Ansicht der richtige Ort.

Opt-out / Opt-in

// Profil-Verknüpfung beenden: löscht uxv_id + usertrax_identify
usertrax.optOut();
// Folgende Events senden profile_opt_out: true (ohne visitor_id)

// Wieder aktivieren / Einwilligung erteilen: neue uxv_id
usertrax.optIn();

Standard ist Opt-out (profilesRequireConsent: false): uxv_id wird automatisch angelegt. Für Einwilligungs-Banner (z. B. TTDSG / ePrivacy) setze:

window.usertraxConfig = {
  profilesRequireConsent: true, // kein uxv_id bis optIn()
};

Solange die Einwilligung aussteht, senden Session- und Conversion-Events profile_opt_out: true. Das ist wichtig: identify() legt email / customer_id in user_data ab, und ohne dieses Flag würde die API daraus ein Profil bilden, bevor je eingewilligt wurde. Sessions und Conversions werden weiterhin normal getrackt — nur die Profil-Verknüpfung unterbleibt.

Mit profiles: false wird nie eine Visitor-ID erzeugt oder gesendet.

Siehe auch Konfiguration & API.

Einschränkungen

Safari / ITP: Script-geschriebenes localStorage kann nach ca. 7 Tagen Inaktivität verfallen. uxv_id ist auf Safari daher nicht monatelang zuverlässig — „Returning Visitor über Monate“ gilt nicht für einen relevanten Traffic-Anteil.
Cross-Domain: uxv_id wird nicht über Domains propagiert (nur die Session-ID via uxs-Parameter). Teams mit mehreren Domains erhalten ohne starke ID (email / customer_id) ein Profil pro Domain.