Web SDK

Kixo Web SDK po dodaniu jednej linijki automatycznie śledzi kliknięcia, odsłony, sesje, błędy, głębokość przewijania, web vitals, rage clicki, dead clicki i dane do map ciepła. Monitorowanie żądań sieciowych jest dostępne jako opcja opt-in. Pakiet jest dostarczany jako natywny moduł ES i działa w nowoczesnych przeglądarkach.

Instalacja

Znacznik script (CDN)

Dodaj snippet przed zamykającym tagiem </head>. Zwróć uwagę na type="module" — jest wymagane, ponieważ SDK jest modułem ES. Odtwarzanie sesji jest wydzielone do osobnego chunka rekordera dopasowanego wersją, który ładuje się dopiero po włączeniu replay, dzięki czemu podstawowy bundle pozostaje mały, gdy replay jest wyłączony.

html

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

Uwaga

SDK odczytuje project_id i api_key z URL skryptu i inicjalizuje się automatycznie. Jeśli chcesz konfigurować opcje w kodzie aplikacji, usuń parametry z URL i wywołaj zamiast tego Kixo.init({...}) — po załadowaniu modułu będzie dostępny globalny obiekt Kixo.

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

Użyj tego, jeśli chcesz konfigurować opcje w kodzie aplikacji zamiast przez URL skryptu. Udostępnia to samo API Kixo co osadzenie z CDN.

bash

npm install @kixo.io/web

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

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

Platformy no-code

Jeśli tworzysz w builderze opartym na AI, takim jak Lovable, Bolt, v0 lub Replit, wklej snippet z tagiem script bezpośrednio do czatu buildera albo do ustawień wstrzykiwania kodu. Większość builderów pozwala dodawać skrypty do <head> witryny.

Konfiguracja

Osadzenie w dwóch linijkach korzysta z poniższych lokalnych ustawień domyślnych analityki. Monitorowanie żądań nadal wymaga opt-in. Session replay celowo nie jest konfigurowany w Kixo.init(): jego włączenie, próbkowanie, ustawienia prywatności, czas trwania i ustawienia przechwytywania pochodzą wyłącznie z dashboardu projektu.

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,
  },

});

Uwaga

Konfiguracja sterowana na poziomie projektu. Ustawienia Dashboard mogą wyłączać lokalne trackery analityczne. Replay w ogóle nie ma lokalnej flagi włączenia: skonfiguruj go w Settings → Session replay, a SDK zastosuje aktualną politykę projektu przy następnym odświeżeniu konfiguracji.

Zdarzenia śledzone automatycznie

Przy domyślnej konfiguracji Kixo automatycznie zbiera te zdarzenia bez dodatkowego kodu:

page_view — każda nawigacja (pierwsze ładowanie i zmiany tras w SPA)
session_start / session_end
click — wszystkie kliknięcia wraz z selektorem elementu
scroll_depth — progi 25 / 50 / 75 / 100 %
rage_click — powtarzane kliknięcia tego samego elementu
dead_click — kliknięcia w elementy nieinteraktywne
error — nieobsłużone wyjątki JavaScript i odrzucone Promise
performance — metryki ładowania strony i Web Vitals (LCP, FCP, FID, CLS, INP, TTFB)
network_request — opcjonalny czas trwania żądania, gdy śledzenie sieci jest włączone
heatmap_click / scroll — dane map cieplnych

Pełną listę znajdziesz w Referencja zdarzeń.

Zdarzenia niestandardowe

Kixo.track()

Wyślij własne zdarzenie z opcjonalnymi właściwościami.

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

Typowane helpery zdarzeń

Wygodna nakładka na Kixo.track() dla zdarzeń, które Kixo rozpoznaje po nazwie (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Typowane wrappery dają walidację właściwości na etapie kompilacji i jedno źródło prawdy dla nazw kluczy — detektor zdarzeń standardowych po stronie backendu dopasowuje je dosłownie.

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()

Powiąż bieżące urządzenie ze znanym użytkownikiem. Zarezerwowane klucze standardowych właściwości mają prefiks $ (zgodnie z konwencją Mixpanel), dzięki czemu nie kolidują z Twoimi własnymi cechami niestandardowymi i trafiają do kolumn profilu w Dashboard. Pełną listę 37 kluczy znajdziesz poniżej w Katalog standardowych właściwości.

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() — oznacz użytkownika na potrzeby segmentacji

Dodaj do bieżącego użytkownika dowolne atrybuty klucz/wartość. Wartości mogą być ciągami znaków, liczbami lub wartości logiczne — forma boolean to najprostszy sposób, by tag użytkownika do późniejszego targetowania w segmentach, kampaniach e-mailowych lub zapytaniach czatu.

// 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' });

Właściwości są zapisywane w localStorage między przeładowaniami i automatycznie dołączane do kolejnych zdarzeń. Możesz używać ich w czacie w promptach takich jak "utwórz kampanię e-mailową dla użytkowników, u których subscribe ma wartość true" — Kixo sam utworzy segment i przygotuje szkic szablonu. Czyszczone przy Kixo.reset().

Kixo.group()

Powiąż użytkownika z firmą lub organizacją.

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

Kixo.reset()

Wyczyść tożsamość, super-properties i zapisaną kolejkę. Wywołaj to przy wylogowaniu, aby kolejne zdarzenia nie były przypisywane poprzedniemu użytkownikowi.

Kixo.reset();

Katalog standardowych właściwości

Zarezerwowane klucze właściwości mają prefiks $, więc nie kolidują z własnymi cechami. Katalog Kixo obejmuje 37 kluczy w 3 uniwersalnych pakietach (tożsamość, geo, cykl życia) oraz 5 pakietach wertykalnych B2B (subskrypcja, e-commerce, media, marketplace, lojalność). Ustaw tylko te, które pasują do Twojego produktu — dashboard dostosuje się i pokaże wyłącznie uzupełnione pakiety.

Tożsamość

Zawsze istotne. Ustawia kolumny nagłówka profilu.

Klucz	Typ	Opis
`$email`	ciąg znaków	Główny adres e-mail, często używany jako klucz do spinania tożsamości.
`$phone`	ciąg znaków	Numer telefonu w formacie E.164.
`$name`	ciąg znaków	Pełna nazwa wyświetlana.
`$first_name`	ciąg znaków	Imię.
`$last_name`	ciąg znaków	Nazwisko.
`$avatar_url`	ciąg znaków	Pełny URL obrazu awatara użytkownika.

Geo

Kontekst geograficzny.

Klucz	Typ	Opis
`$country`	ciąg znaków	Kod kraju zgodny ze standardem ISO 3166.
`$city`	ciąg znaków	Nazwa miasta.
`$region`	ciąg znaków	Stan lub prowincja.
`$timezone`	ciąg znaków	Strefa IANA, np. `America/Los_Angeles`.
`$language`	ciąg znaków	Tag IETF, np. `en` lub `ru-RU`.
`$locale`	ciąg znaków	Pełny identyfikator ustawień regionalnych.

Cykl życia

Kiedy ostatnio go widzieliśmy.

Klucz	Typ	Opis
`$created`	ISO8601	Czas rejestracji lub utworzenia konta.
`$last_seen`	ISO8601	Czas ostatniej interakcji.

Subskrypcja

Ustaw, jeśli Twój produkt ma plany.

Klucz	Typ	Opis
`$plan`	ciąg znaków	Slug poziomu — `free`, `pro`, `enterprise`.
`$subscription_status`	ciąg znaków	`active` / `trial` / `cancelled` / `past_due`.
`$trial_ends`	ISO8601	Koniec bieżącego okresu próbnego.
`$mrr`	liczba	Miesięczny przychód powtarzalny w walucie konta.
`$subscription_started`	ISO8601	Początek bieżącej subskrypcji.

E-commerce

Ustaw, jeśli sprzedajesz produkty.

Klucz	Typ	Opis
`$lifetime_orders`	liczba	Liczba zrealizowanych zamówień.
`$lifetime_revenue`	liczba	Łączne wydatki.
`$aov`	liczba	Średnia wartość zamówienia.
`$last_purchase`	ISO8601	Ostatni udany zakup.
`$first_purchase`	ISO8601	Pierwszy udany zakup.
`$cart_abandoned_count`	liczba	Łączna liczba porzuconych koszyków.

Media

Ustaw, jeśli publikujesz treści.

Klucz	Typ	Opis
`$content_tier`	ciąg znaków	`free` / `premium` / `paid`.
`$subscribed_categories`	Ciąg CSV lub tablica	Kategorie obserwowane przez użytkownika.
`$watch_time_total`	liczba	Łączny czas oglądania w sekundach.
`$last_played`	ISO8601	Ostatnie rozpoczęcie odtwarzania.

Marketplace

Ustaw, jeśli Twój produkt działa jako platforma dwustronna.

Klucz	Typ	Opis
`$seller_tier`	ciąg znaków	Slug poziomu po stronie sprzedawcy.
`$buyer_tier`	ciąg znaków	Slug poziomu po stronie kupującego.
`$listings_count`	liczba	Aktywne ogłoszenia użytkownika.
`$reviews_count`	liczba	Opinie otrzymane przez użytkownika.
`$verified`	wartość logiczna	Status KYC.

Lojalność

Ustaw, jeśli korzystasz z programów lojalnościowych lub nagród.

Klucz	Typ	Opis
`$loyalty_points`	liczba	Bieżące saldo punktów do wykorzystania.
`$vip_level`	ciąg znaków	Slug poziomu VIP.
`$referral_count`	liczba	Skuteczne polecenia przypisane do tego użytkownika.

Wskazówka

Nie widzisz tu swojego wzorca? Dla cech niestandardowych używaj zwykłych kluczy. Pojawią się w panelu Custom Traits w Dashboard, bez zaśmiecania kolumn profilu. Pięć pakietów branżowych powyżej to celowe propozycje najczęstszych struktur B2B — terminologia specyficzna dla klienta, np. shipping_plan, pozostaje bez prefiksu.

Super-properties

Pary klucz-wartość przypisane do sesji, automatycznie dołączane do każdego wysyłanego zdarzenia. To nie to samo co cechy identify(), które opisują tożsamość; super-properties opisują kontekst sesji — aktywny wariant A/B, wariant buildu, włączone flagi funkcji czy źródło afiliacyjne. Są zapisywane w localStorage między przeładowaniami i czyszczone przy reset(). Jeśli klucze się powtórzą, pierwszeństwo zawsze mają właściwości per-event properties przekazane w track().

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();

Heatmapy

Rejestrowanie map cieplnych jest domyślnie włączone — obejmuje kliknięcia i głębokość przewijania, oba próbkowane w 100 %. Ruch myszy jest opcjonalny (to duży wolumen danych; włączaj go dla konkretnych stron tylko wtedy, gdy ma to sens).

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

Replay sesji

Session replay zapisuje migawkę DOM z rrweb oraz strumień mutacji, dzięki czemu dashboard może odtworzyć stronę jako przewijalną sesję obok ścieżki zdarzeń. To rekonstrukcja DOM, a nie nagranie ekranu. Replay jest domyślnie wyłączone. Włączysz go dla projektu w Dashboard → Ustawienia → Odtwarzanie sesji; nie wymaga to zmian w kodzie aplikacji. Po włączeniu rejestrator jest pobierany z osobnego chunka w pasującej wersji.

Uwaga

Źródłem prawdy jest dashboard. Ustawisz tam Enable replay, Mask inputs, maksymalny czas trwania oraz zaawansowane opcje przechwytywania. captureOnCellular jest zapisywane w tej samej polityce projektu dla iOS i Android; przeglądarki nie udostępniają wiarygodnej informacji o połączeniu przez Wi‑Fi lub sieć komórkową, więc Web SDK zgłasza to ustawienie, ale je ignoruje, bo dotyczy wyłącznie natywnych SDK.

Co jest maskowane

Replay zaprojektowano tak, żeby można go było bezpiecznie włączyć. Wrażliwe treści chronią trzy warstwy zabezpieczeń, wszystkie domyślnie włączone:

Maskowanie pól ustawiasz na poziomie projektu — gdy w Dashboard jest włączone ustawienie Maskowanie pól (domyślnie), wpisywane znaki są zastępowane gwiazdkami, zanim opuszczą przeglądarkę. Wyłączaj je tylko w konkretnym przypadku o niskiej wrażliwości; pola związane z tożsamością, uwierzytelnianiem i płatnościami pozostają zamaskowane.
Atrybut data-kixo-mask blokuje element i całe jego poddrzewo. Dodaj go do każdego kontenera, który może zawierać dane osobowe lub poufne treści; w odtworzeniu pojawi się placeholder zamiast tekstu i zawartości DOM tego poddrzewa.
html
```
<div data-kixo-mask>
  
  
</div>
```
Pola wrażliwe są zawsze maskowane — pola wyglądające na hasło, numer karty, CVV, SSN, sekret lub token (na podstawie type, name, id albo autocomplete) są maskowane nawet wtedy, gdy ustawienie projektu Maskowanie pól jest wyłączone. Widoczny tekst i serializowane atrybuty DOM również przechodzą przez filtr PII Kixo przed wysłaniem.

Zbieranie danych

SDK zbiera dane z trackerów włączonych w integracji i ustawieniach projektu, a także zdarzenia i właściwości wysyłane przez aplikację.

Dokąd trafiają nagrania

SDK kompresuje zdarzenia rrweb do segmentów gzip o ograniczonym rozmiarze, pobiera z Kixo podpisany URL wysyłki ograniczony do projektu i przesyła te segmenty bezpośrednio do magazynu replay. Odtworzoną sesję otworzysz w Odtwarzanie sesji → Sesje; znajdziesz tam też ścieżkę analityczną tej samej sesji.

Uwaga

Dostępność Replay zależy od Twojego planu. To, ile sesji jest przechwytywanych i przechowywanych, zależy od planu projektu; w niższych planach Kixo nadal zapisuje lekkie metadane sesji, dzięki czemu sesja pojawia się na listach i w analityce.

Flagi funkcji

Sprawdzaj wartości flag w czasie działania przez Kixo.getFeatureFlag().

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

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

Wysyłka danych i działanie offline

SDK lokalnie kolejkowuje zdarzenia, wysyła je partiami i ponawia przejściowe błędy z użyciem backoffu. Jeśli zbieranie danych zostanie wstrzymane w ustawieniach projektu, nowe zdarzenia nie będą wysyłane, dopóki nie zostanie ponownie włączone.

Diagnostyka

Migawka stanu tylko do odczytu — przydatna przy debugowaniu w narzędziach deweloperskich, gdy trzeba sprawdzić: „dlaczego moje zdarzenia nie docierają?”.

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