Web SDK

Das Kixo Web SDK erfasst mit einer einzigen Einbindung automatisch Klicks, Seitenaufrufe, Sitzungen, Fehler, Scrolltiefe, Web Vitals, Rage Clicks, Dead Clicks und Heatmap-Daten. Das Monitoring von Netzwerkanfragen ist optional per Opt-in verfügbar. Es wird als natives ES-Modul ausgeliefert und läuft in modernen Browsern.

Installation

Script-Tag (CDN)

Füge das Snippet direkt vor dem schließenden </head>-Tag ein. Beachte type="module" — das ist erforderlich, weil das SDK ein ES-Modul ist. Session Replay ist per Code-Splitting in einen versionsgleichen Recorder-Chunk ausgelagert, der erst geladen wird, wenn Replay aktiviert ist. So bleibt das Basis-Bundle klein, solange Replay ausgeschaltet ist.

html

<script
  type="module"
  src="https://cdn.kixo.io/kixo.min.js?project_id=YOUR_PROJECT_ID&api_key=YOUR_API_KEY">
</script>

Hinweis

Das SDK liest project_id und api_key aus der Script-URL und initialisiert sich selbst. Wenn du Optionen im Anwendungscode konfigurieren willst, lass die URL-Parameter weg und rufe stattdessen Kixo.init({...}) auf — das globale Objekt Kixo ist verfügbar, sobald das Modul geladen ist.

html

<script type="module" src="https://cdn.kixo.io/kixo.min.js"></script>
<script type="module">
  Kixo.init({
    projectId: 'YOUR_PROJECT_ID',
    apiKey:    'YOUR_API_KEY',
  });
</script>

npm

Verwende dies, wenn du Optionen im Anwendungscode statt über die Script-URL konfigurieren möchtest. Es stellt dieselbe Kixo API wie die CDN-Einbindung bereit.

bash

npm install @kixo.io/web

import Kixo from '@kixo.io/web';

Kixo.init({
  projectId: 'YOUR_PROJECT_ID',
  apiKey: 'YOUR_API_KEY',
});

No-Code-Plattformen

Wenn du mit einem AI-gestützten Builder wie Lovable, Bolt, v0 oder Replit arbeitest, füge das Script-Tag-Snippet direkt in den Chat oder in die Einstellungen für Code-Injection deines Builders ein. Die meisten Builder unterstützen das Einfügen von Scripts im <head> deiner Website.

Konfiguration

Die zweizeilige Einbindung verwendet die lokalen Analytics-Standardwerte unten. Das Monitoring von Anfragen bleibt optional per Opt-in. Session Replay ist bewusst nicht Teil von Kixo.init(): Aktivierung, Sampling, Datenschutz, Dauer und Aufzeichnungseinstellungen kommen ausschließlich aus dem Projekt-Dashboard.

Kixo.init({
  projectId: 'YOUR_PROJECT_ID',     // required
  apiKey:    'YOUR_API_KEY',         // required

  // Per-tracker toggles — all default to true except network.
  autoTrack: {
    pageViews:   true,
    clicks:      true,
    scrollDepth: true,
    sessions:    true,
    forms:       true,
    network:     false,     // opt in only when you need request telemetry
    errors:      true,
    performance: true,
    rageClicks:  true,
    deadClicks:  true,
  },

  // Heatmap recording (clicks + scroll on by default; mouse-move opt-in).
  heatmap: {
    enabled: true,
    clicks:  true,
    moves:   false,
    scroll:  true,
  },

});

Hinweis

Projektgesteuerte Konfiguration. Lokale Analytics-Tracker lassen sich in den Dashboard-Einstellungen deaktivieren. Für Replay gibt es lokal überhaupt kein explizites Aktivierungs-Flag: Konfiguriere es unter Settings → Session replay, und das SDK übernimmt beim nächsten Aktualisieren der Konfiguration die aktuelle Projektrichtlinie.

Automatisch erfasste Events

Mit der Standardkonfiguration erfasst Kixo diese Events automatisch, ganz ohne zusätzlichen Code:

page_view — jede Navigation (Erstaufruf + SPA-Routenwechsel)
session_start / session_end
click — alle Klickinteraktionen mit Elementselektor
scroll_depth — Schwellenwerte bei 25 / 50 / 75 / 100 %
rage_click — wiederholte Klicks auf dasselbe Element
dead_click — Klicks auf nicht interaktive Elemente
error — nicht abgefangene JavaScript-Ausnahmen + abgelehnte Promises
performance — Kennzahlen zu Seitenladezeit und Web Vitals (LCP, FCP, FID, CLS, INP, TTFB)
network_request — optionales Timing von Requests, wenn das Netzwerk-Tracking aktiviert ist
heatmap_click / scroll — Heatmap-Daten

Die vollständige Liste findest du in Event-Referenz.

Benutzerdefinierte Events

Kixo.track()

Sende ein benutzerdefiniertes Event mit optionalen Properties.

Kixo.track('purchase_completed', {
  product_id: 'SKU-123',
  amount: 49.99,
  currency: 'USD',
});

Typisierte Event-Helfer

Komfort-Wrapper um Kixo.track() für Events, die Kixo am Namen erkennt (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Typisierte Wrapper bieten Property-Validierung zur Compile-Zeit und eine zentrale Quelle für Schlüsselnamen — der Standard-Event-Detektor im Backend gleicht sie exakt ab.

Kixo.trackPurchase({ amount: 49.99, currency: 'USD', productId: 'pro_yearly' });

Kixo.trackSubscriptionStart({
  plan: 'pro',
  amount: 9.99,
  currency: 'USD',
  interval: 'month',
});

Kixo.trackSignup({ method: 'google' });
Kixo.trackTrialStart({ plan: 'pro', days: 14 });
Kixo.trackCancel({ plan: 'pro', reason: 'too_expensive' });
Kixo.trackUpgrade({ fromPlan: 'free', toPlan: 'pro' });
Kixo.trackActivation({ event: 'first_post_published' });
Kixo.trackShare({ channel: 'twitter', contentId: 'post_123' });
Kixo.trackInvite({ channel: 'email', recipientCount: 5 });

Kixo.identify()

Verknüpft das aktuelle Gerät mit einem bekannten Nutzer. Reservierte Standard-Property-Keys tragen den Präfix $ (Mixpanel-Konvention), damit sie von deinen eigenen Custom Traits getrennt bleiben und in die Profilspalten des Dashboards übernommen werden — die vollständige Liste mit 37 Keys findest du unten unter Standardkatalog für Properties.

Kixo.identify('user_123', {
  $email:  'jane@example.com',     // identity
  $name:   'Jane Doe',              // identity
  $plan:   'pro',                   // subscription pack
  $lifetime_orders: 12,             // e-commerce pack
  signup_source: 'twitter_ad',      // custom trait
});

Kixo.setUserProperty() — Nutzer für die Segmentierung markieren

Hängt dem aktuellen Nutzer beliebige Schlüssel/Wert-Attribute an. Werte können Strings, Zahlen oder boolesche Werte sein — die boolesche Form ist der sauberste Weg, einen Nutzer für spätere Zielgruppen in Segmenten, E-Mail-Kampagnen oder Chat-Abfragen zu Tag.

// Tag a user as subscribed — instant segment "Subscribed users"
Kixo.setUserProperty('subscribe', true);

// Mark a VIP — used in campaign targeting + chat ("show me VIPs")
Kixo.setUserProperty('vip', true);

// Numeric and string values work too
Kixo.setUserProperty('plan_tier', 'enterprise');
Kixo.setUserProperty('lifetime_orders', 42);

// Bulk-set
Kixo.setUserProperties({ subscribe: true, plan_tier: 'enterprise' });

Properties bleiben in localStorage über Reloads hinweg erhalten und werden automatisch an nachfolgende Events angehängt. Nutze sie in Kixo Chat mit Prompts wie „E-Mail-Kampagne für Nutzer erstellen, bei denen subscribe auf true steht“ — Kixo erstellt daraus automatisch ein Segment und einen Vorlagenentwurf. Gelöscht bei Kixo.reset().

Kixo.group()

Verknüpft den Nutzer mit einem Unternehmen oder einer Organisation.

Kixo.group('company_456', {
  name: 'Acme Inc',
  plan: 'enterprise',
});

Kixo.reset()

Löscht Identität, Super-Properties und die persistierte Warteschlange. Rufe das beim Logout auf, damit nachfolgende Events nicht dem vorherigen Nutzer zugeordnet werden.

Kixo.reset();

Standardkatalog für Properties

Reservierte Property-Schlüssel tragen das Präfix $, damit sie klar von deinen eigenen Traits getrennt sind. Der Katalog von Kixo umfasst 37 Schlüssel in 3 universellen Paketen (Identität, Geo, Lebenszyklus) und 5 B2B-Fachpaketen (Subscription, E-Commerce, Medien, Marktplatz, Loyalität). Setze einfach die Schlüssel, die zu deinem Produkt passen — das Dashboard passt sich an und zeigt nur die Pakete an, die du tatsächlich befüllst.

Identität

Immer relevant. Legt die Spalten im Profilkopf fest.

Schlüssel	Typ	Beschreibung
`$email`	String	Primäre E-Mail-Adresse, oft der Schlüssel zum Zusammenführen von Identitäten.
`$phone`	String	Telefonnummer im E.164-Format.
`$name`	String	Vollständiger Anzeigename.
`$first_name`	String	Vorname.
`$last_name`	String	Nachname.
`$avatar_url`	String	Vollständige URL zum Avatarbild des Nutzers.

Geo

Geografischer Kontext.

Schlüssel	Typ	Beschreibung
`$country`	String	Ländercode nach ISO 3166.
`$city`	String	Stadtname.
`$region`	String	Bundesland oder Provinz.
`$timezone`	String	IANA-Zeitzone wie `America/Los_Angeles`.
`$language`	String	IETF-Tag wie `en` oder `ru-RU`.
`$locale`	String	Vollständiger Locale-Identifier.

Lebenszyklus

Wann wir sie zuletzt gesehen haben.

Schlüssel	Typ	Beschreibung
`$created`	ISO8601	Zeitpunkt der Registrierung oder Kontoerstellung.
`$last_seen`	ISO8601	Zeitpunkt der letzten Interaktion.

Abonnement

Setzen, wenn dein Produkt Tarife hat.

Schlüssel	Typ	Beschreibung
`$plan`	String	Stufen-Slug — `free`, `pro`, `enterprise`.
`$subscription_status`	String	`active` / `trial` / `cancelled` / `past_due`.
`$trial_ends`	ISO8601	Wann die aktuelle Testphase endet.
`$mrr`	Zahl	Monatlich wiederkehrender Umsatz in der Kontowährung.
`$subscription_started`	ISO8601	Beginn des aktuellen Abonnements.

E-Commerce

Setzen, wenn du Produkte verkaufst.

Schlüssel	Typ	Beschreibung
`$lifetime_orders`	Zahl	Anzahl abgeschlossener Bestellungen.
`$lifetime_revenue`	Zahl	Gesamtausgaben.
`$aov`	Zahl	Durchschnittlicher Bestellwert.
`$last_purchase`	ISO8601	Letzter erfolgreicher Kauf.
`$first_purchase`	ISO8601	Erster erfolgreicher Kauf.
`$cart_abandoned_count`	Zahl	Gesamtzahl der Warenkorbabbrüche.

Medien

Setzen, wenn du Inhalte veröffentlichst.

Schlüssel	Typ	Beschreibung
`$content_tier`	String	`free` / `premium` / `paid`.
`$subscribed_categories`	CSV-String oder Array	Kategorien, denen der Nutzer folgt.
`$watch_time_total`	Zahl	Gesamte Wiedergabezeit in Sekunden.
`$last_played`	ISO8601	Zeitpunkt des letzten Wiedergabestarts.

Marktplatz

Setzen, wenn dein Produkt eine zweiseitige Plattform ist.

Schlüssel	Typ	Beschreibung
`$seller_tier`	String	Slug der Verkäuferstufe.
`$buyer_tier`	String	Tier-Slug auf Käuferseite.
`$listings_count`	Zahl	Aktive Einträge des Nutzers.
`$reviews_count`	Zahl	Bewertungen, die der Nutzer erhalten hat.
`$verified`	boolesch	KYC-Status.

Loyalität

Für Engagement- und Bonusprogramme setzen.

Schlüssel	Typ	Beschreibung
`$loyalty_points`	Zahl	Aktuell einlösbarer Punktestand.
`$vip_level`	String	VIP-Stufen-Slug.
`$referral_count`	Zahl	Erfolgreiche Empfehlungen, die diesem Nutzer zugeschrieben werden.

Tipp

Dein Muster ist nicht dabei? Verwende für Custom Traits einfach ungeprefxte Keys. Sie erscheinen im Dashboard im Bereich „Custom Traits“, ohne die Profilspalten zu überladen. Die fünf Vertical Packs oben sind bewusst gewählte Annahmen für die häufigsten B2B-Modelle — kundenspezifische Begriffe (z. B. shipping_plan) bleiben ohne Präfix.

Super-Properties

Schlüssel/Wert-Paare pro Sitzung, die automatisch an jedes ausgehende Event angehängt werden. Anders als identify() Traits, die die Identität beschreiben, erfassen Super-Properties den Sitzungskontext — etwa die aktive A/B-Variante, den Build-Typ, aktivierte Feature-Flags oder den Affiliate-Referrer. Sie bleiben in localStorage über Reloads hinweg erhalten und werden bei reset() gelöscht. Ereignisspezifische properties in track() haben bei gleichem Schlüssel immer Vorrang.

Kixo.setSuperProperty('build_flavor', 'beta');
Kixo.setSuperProperties({ ab_variant: 'B', referrer_campaign: 'autumn-launch' });

// Sugar for A/B tracking — keys as 'experiment_<id>' so backend
// can run direct WHERE filters on experiment analysis.
Kixo.setExperimentVariant('checkout_v2', 'variant_a');

Kixo.unsetSuperProperty('build_flavor');
Kixo.clearSuperProperties();

Heatmaps

Die Heatmap-Aufzeichnung ist standardmäßig aktiv — Klicks und Scrolltiefe jeweils mit 100 % Sampling. Mausbewegungen sind optional (hohes Volumen; bei Bedarf pro Seite aktivieren).

Kixo.init({
  projectId: 'YOUR_PROJECT_ID',
  apiKey:    'YOUR_API_KEY',
  heatmap:   { moves: true },  // turn on full-resolution mouse-move
});

Sitzungswiedergabe

Session Replay zeichnet einen rrweb-DOM-Snapshot und einen Mutationsstrom auf, damit das Dashboard die Seite als durchsuchbare Sitzung zusammen mit dem Event-Verlauf rekonstruieren kann. Dabei handelt es sich um eine DOM-Rekonstruktion, nicht um eine Bildschirmaufzeichnung als Video. Replay ist standardmäßig deaktiviert. Aktiviere es für das Projekt unter Dashboard → Einstellungen → Sitzungswiedergabe; Änderungen am Anwendungscode sind nicht nötig. Nach der Aktivierung wird der Recorder aus einem separaten versionsgleichen Chunk geladen.

Hinweis

Das Dashboard ist die maßgebliche Quelle. Dort legst du Enable replay, Mask inputs, die maximale Dauer und die erweiterten Erfassungsoptionen fest. captureOnCellular wird in derselben Projektrichtlinie für iOS und Android gespeichert; Browser liefern jedoch kein verlässliches Signal für WLAN oder Mobilfunk, daher meldet das Web SDK diese nur nativ verfügbare Einschränkung und ignoriert sie.

Was maskiert wird

Replay ist so ausgelegt, dass du es bedenkenlos aktivieren kannst. Drei Ebenen schützen sensible Inhalte, alle standardmäßig aktiv:

Die Eingabemaskierung wird auf Projektebene gesteuert. — solange im Dashboard Eingaben maskieren aktiviert ist (Standard), werden eingegebene Zeichen noch im Browser durch Sternchen ersetzt, bevor sie ihn verlassen. Deaktiviere das nur für einen konkreten, wenig sensiblen Anwendungsfall; Felder für Identität, Authentifizierung und Zahlungen bleiben weiterhin maskiert.
Das Attribut data-kixo-mask sperrt ein Element und seinen gesamten Teilbaum. Setze es auf jeden Container, der personenbezogene oder vertrauliche Inhalte enthalten kann; im Replay erscheint dann ein Platzhalter statt des Textes oder DOM-Inhalts dieses Teilbaums.
html
```
<div data-kixo-mask>
  
  
</div>
```
Sensible Felder werden immer maskiert. — Eingaben, die wie ein Passwort, eine Kartennummer, CVV, SSN, ein Secret oder ein Token aussehen (anhand von type, name, id oder autocomplete), werden auch dann maskiert, wenn die Projekteinstellung Eingaben maskieren deaktiviert ist. Sichtbarer Text und serialisierte DOM-Attribute laufen vor dem Upload zusätzlich durch den PII-Sanitizer von Kixo.

Datenerfassung

Das SDK erfasst die Tracker, die in deiner Integration und in den Projekteinstellungen aktiviert sind, sowie die Events und Properties, die deine Anwendung sendet.

Wohin Aufzeichnungen gespeichert werden

Das SDK komprimiert rrweb-Events per gzip in Segmente mit begrenzter Größe, holt bei Kixo eine projektspezifische signierte Upload-URL und lädt diese Segmente direkt in den Replay-Speicher hoch. Öffne die rekonstruierte Sitzung unter Replay → Sitzungen; dort ist auch der Analytics-Verlauf derselben Sitzung verlinkt.

Hinweis

Replay ist von deinem Tarif abhängig. Wie viele Sessions erfasst und aufbewahrt werden, hängt von deinem Projektplan ab; in kleineren Tarifen zeichnet Kixo trotzdem schlanke Session-Metadaten auf, damit die Session in Listen und Auswertungen erscheint.

Feature Flags

Prüfe Flag-Werte zur Laufzeit über Kixo.getFeatureFlag().

const variant = Kixo.getFeatureFlag('new_checkout');

if (variant === 'enabled') {
  showNewCheckout();
} else {
  showLegacyCheckout();
}

Auslieferung und Offline-Verhalten

Das SDK puffert Events lokal, sendet sie gebündelt und wiederholt vorübergehende Fehler mit Backoff. Wenn die Erfassung in den Projekteinstellungen pausiert ist, werden neue Events erst wieder gesendet, sobald die Erfassung wieder aktiviert wird.

Diagnostik

Schreibgeschützter Zustands-Snapshot — hilfreich für die Fehlersuche in den DevTools, wenn du wissen willst: „Warum kommen meine Events nicht an?“

const diag = Kixo.diagnostics();
console.log(diag);