Web SDK

Kixo Web SDK po vložení jediného řádku automaticky sleduje kliknutí, zobrazení stránek, relace, chyby, hloubku posunu, web vitals, rage clicky, dead clicky a data pro heatmapy. Monitorování síťových požadavků je dostupné jako volitelné nastavení. Dodává se jako nativní ES modul a funguje v moderních prohlížečích.

Instalace

Script tag (CDN)

Úryvek vložte před ukončovací tag </head>. Všimněte si type="module" — je povinné, protože SDK je ES modul. Session replay je rozdělený do samostatného recorder chunku se stejnou verzí, který se načte až po zapnutí replaye, takže základní bundle zůstane při vypnutém replayi malý.

html

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

Poznámka

SDK načte project_id a api_key z URL skriptu a samo se inicializuje. Pokud chcete volby nastavovat v kódu aplikace, parametry v URL vynechte a místo toho zavolejte Kixo.init({...}) — globální objekt Kixo je k dispozici po načtení modulu.

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

Použijte, když chcete volby nastavovat v kódu aplikace místo přes URL skriptu. Zpřístupňuje stejné Kixo API jako vložení přes CDN.

bash

npm install @kixo.io/web

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

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

No-code platformy

Pokud web stavíte v AI builderu, jako je Lovable, Bolt, v0 nebo Replit, vložte snippet se script tagem přímo do chatu builderu nebo do nastavení pro vkládání kódu. Většina builderů umí přidat skripty do <head> webu.

Konfigurace

Dvouřádkové vložení používá níže uvedené místní výchozí nastavení analytiky. Monitorování požadavků zůstává volitelné. Session replay záměrně není součástí Kixo.init(): jeho zapnutí, vzorkování, ochranu soukromí, délku i nastavení záznamu řídí výhradně dashboard 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,
  },

});

Poznámka

Konfigurace řízená projektem. V nastavení Dashboardu můžete vypnout lokální analytické trackery. Replay nemá žádný lokální přepínač pro vynucené zapnutí: nastavuje se vSettings → Session replay a SDK při dalším obnovení konfigurace převezme aktuální pravidla projektu.

Automaticky sledované události

Ve výchozím nastavení Kixo automaticky zachycuje tyto události bez dalšího kódu:

page_view — každá navigace (první načtení + změny tras v SPA)
session_start / session_end
click — všechna kliknutí včetně selektoru prvku
scroll_depth — prahy 25 / 50 / 75 / 100 %
rage_click — opakovaná kliknutí na stejný prvek
dead_click — kliknutí na neinteraktivní prvky
error — nezachycené výjimky JavaScript a zamítnuté promise
performance — metriky načítání stránky a Web Vitals (LCP, FCP, FID, CLS, INP, TTFB)
network_request — volitelné časování požadavků při zapnutém sledování sítě
heatmap_click / scroll — data pro heatmapu

Úplný seznam najdete v Referenční přehled událostí.

Vlastní události

Kixo.track()

Odešle vlastní událost s volitelnými vlastnostmi.

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

Typované pomocné funkce pro události

Nadstavba nad Kixo.track() pro události, které Kixo rozpoznává podle názvu (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Typové obálky přinášejí kontrolu vlastností už při kompilaci a drží názvy klíčů na jednom místě — backendový detektor standardních událostí porovnává názvy doslova.

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

Přiřadí aktuální zařízení ke známému uživateli. Vyhrazené standardní klíče vlastností mají prefix $ (konvence Mixpanel), takže se oddělí od vašich vlastních atributů a promítnou se do sloupců profilu v dashboardu — úplný seznam všech 37 klíčů najdete níže v Katalog standardních vlastností.

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() — označí uživatele pro segmentaci

Přidá k aktuálnímu uživateli libovolné atributy ve formátu klíč/hodnota. Hodnoty mohou být řetězce, čísla nebo booleany — logická hodnota je nejčistší způsob, jak uživatele štítek pro pozdější cílení v segmentech, e-mailových kampaních nebo dotazech v chatu.

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

Vlastnosti se ukládají do localStorage i po obnovení stránky a automaticky se připojují k dalším událostem. V chatu je můžete použít v zadáních jako "vytvoř e-mailovou kampaň pro uživatele, kteří mají subscribe nastavené na true" — Kixo automaticky vytvoří segment a připraví návrh šablony. Mažou se při Kixo.reset().

Kixo.group()

Přiřadí uživatele ke společnosti nebo organizaci.

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

Kixo.reset()

Vymaže identitu, super-properties i uloženou frontu. Volejte při odhlášení, aby se další události nepřiřadily předchozímu uživateli.

Kixo.reset();

Katalog standardních vlastností

Vyhrazené klíče vlastností mají prefix $, aby byly oddělené od vašich vlastních atributů. Katalog Kixo pokrývá 37 klíčů ve 3 univerzálních sadách (identita, geo, životní cyklus) a 5 oborových sadách pro B2B (předplatné, e-commerce, média, marketplace, věrnost). Nastavte jen ty, které dávají smysl pro váš produkt — dashboard se přizpůsobí a zobrazí jen sady, které skutečně používáte.

Identita

Vždy relevantní. Určuje sloupce v záhlaví profilu.

Klíč	Typ	Popis
`$email`	řetězec	Primární e-mail, často používaný jako merge key pro spojování identit.
`$phone`	řetězec	Telefonní číslo ve formátu E.164.
`$name`	řetězec	Celé zobrazované jméno.
`$first_name`	řetězec	Jméno.
`$last_name`	řetězec	Příjmení.
`$avatar_url`	řetězec	Plná URL adresa avataru uživatele.

Geo

Geografický kontext.

Klíč	Typ	Popis
`$country`	řetězec	Kód země podle ISO 3166.
`$city`	řetězec	Název města.
`$region`	řetězec	Stát nebo provincie.
`$timezone`	řetězec	IANA zóna, například `America/Los_Angeles`.
`$language`	řetězec	IETF tag, například `en` nebo `ru-RU`.
`$locale`	řetězec	Úplný identifikátor locale.

Životní cyklus

Kdy jsme ho zaznamenali.

Klíč	Typ	Popis
`$created`	ISO8601	Čas registrace nebo vytvoření účtu.
`$last_seen`	ISO8601	Čas poslední interakce.

Předplatné

Nastavte, pokud má váš produkt tarify.

Klíč	Typ	Popis
`$plan`	řetězec	Slug tarifu — `free`, `pro`, `enterprise`.
`$subscription_status`	řetězec	`active` / `trial` / `cancelled` / `past_due`.
`$trial_ends`	ISO8601	Kdy končí aktuální zkušební období.
`$mrr`	číslo	Měsíční opakované tržby v měně účtu.
`$subscription_started`	ISO8601	Kdy začalo aktuální předplatné.

E-commerce

Nastavte, pokud prodáváte produkty.

Klíč	Typ	Popis
`$lifetime_orders`	číslo	Počet dokončených objednávek.
`$lifetime_revenue`	číslo	Celková útrata.
`$aov`	číslo	Průměrná hodnota objednávky.
`$last_purchase`	ISO8601	Poslední úspěšný nákup.
`$first_purchase`	ISO8601	První úspěšný nákup.
`$cart_abandoned_count`	číslo	Celkový počet opuštění košíku.

Média

Nastavte, pokud publikujete obsah.

Klíč	Typ	Popis
`$content_tier`	řetězec	`free` / `premium` / `paid`.
`$subscribed_categories`	Řetězec CSV nebo pole	Kategorie, které uživatel sleduje.
`$watch_time_total`	číslo	Celková doba sledování v sekundách.
`$last_played`	ISO8601	Čas posledního spuštění přehrávání.

Marketplace

Nastavte, pokud provozujete dvoustrannou platformu.

Klíč	Typ	Popis
`$seller_tier`	řetězec	Slug tarifu na straně prodejce.
`$buyer_tier`	řetězec	Slug tarifu na straně kupujícího.
`$listings_count`	číslo	Aktivní nabídky, které uživatel vlastní.
`$reviews_count`	číslo	Recenze, které uživatel obdržel.
`$verified`	boolean	Stav KYC.

Věrnost

Nastavte pro programy zapojení a odměn.

Klíč	Typ	Popis
`$loyalty_points`	číslo	Aktuální zůstatek bodů k uplatnění.
`$vip_level`	řetězec	Slug VIP úrovně.
`$referral_count`	číslo	Úspěšná doporučení připsaná tomuto uživateli.

Tip

Nevidíte svůj případ? Pro vlastní atributy používejte klíče bez prefixu. V dashboardu se zobrazí v panelu Custom Traits, aniž by zaplnily sloupce profilu. Pět oborových balíčků výše je jen praktický odhad nejběžnějších modelů v B2B — terminologie specifická pro zákazníka (např. shipping_plan) zůstává bez prefixu.

Super-properties

Klíče a hodnoty navázané na relaci, které se automaticky připojují ke každé odchozí události. Na rozdíl od atributů identify(), které popisují identitu, super-properties popisují kontext relace — aktivní variantu A/B testu, variantu buildu, zapnuté feature flagy nebo affiliate ref. Ukládají se do localStorage i po obnovení stránky a mažou se při reset(). Při kolizi klíčů mají vždy přednost vlastnosti properties předané do 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

Záznam pro heatmapy je ve výchozím nastavení zapnutý — kliknutí i hloubka posunu, obojí se vzorkováním 100 %. Pohyb myši je volitelný (má vysoký objem; zapínejte ho po jednotlivých stránkách jen tam, kde je opravdu užitečný).

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

Přehrání relace

Session replay zaznamenává snapshot DOM a proud mutací z rrweb, aby dashboard mohl stránku zrekonstruovat jako přehrávatelnou relaci vedle časové osy událostí. Jde o rekonstrukci DOM, ne o záznam obrazovky. Replay je ve výchozím stavu vypnuto. Zapnete ho pro projekt v Přehled → Nastavení → Přehrání relace; není potřeba měnit kód aplikace. Po zapnutí se recorder stáhne ze samostatného chunku se stejnou verzí.

Poznámka

Dashboard je zdroj pravdy. Tam nastavíte Enable replay, Mask inputs, maximální délku i pokročilé volby záznamu. captureOnCellular se ukládá do stejné projektové konfigurace pro iOS a Android; prohlížeče nespolehlivě rozlišují Wi‑Fi od mobilní sítě, takže SDK pro web toto omezení z nativních aplikací jen nahlásí a ignoruje.

Co se maskuje

Replay je navržený tak, aby se dal bezpečně zapnout. Citlivý obsah chrání tři vrstvy, všechny jsou ve výchozím nastavení zapnuté:

Maskování vstupů řídí projekt — pokud je v Dashboardu zapnuté nastavení Maskovat vstupy (výchozí stav), zadané znaky se ještě před odesláním z prohlížeče nahradí hvězdičkami. Vypínejte ho jen pro konkrétní potřebu s nízkou citlivostí; pole pro identitu, ověřování a platby zůstávají maskovaná.
Atribut data-kixo-mask zablokuje prvek i celý jeho podstrom. Přidejte ho na každý kontejner, který může obsahovat osobní nebo důvěrný obsah; v přehrání se místo něj zobrazí zástupný prvek, ne text ani obsah DOM z daného podstromu.
html
```
<div data-kixo-mask>
  
  
</div>
```
Citlivá pole se maskují vždy — vstupy, které vypadají jako heslo, číslo karty, CVV, SSN, tajný údaj nebo token (podle type, name, id nebo autocomplete), se maskují i tehdy, když je nastavení projektu Maskovat vstupy vypnuté. Viditelný text i serializované atributy DOM navíc před odesláním procházejí PII sanitizací v Kixo.

Sběr dat

SDK zachycuje trackery zapnuté v integraci a nastavení projektu i události a vlastnosti, které odesílá vaše aplikace.

Kam se nahrávky ukládají

SDK komprimuje události rrweb pomocí gzipu do segmentů s omezenou velikostí, vyžádá si od Kixo podepsanou URL pro nahrání v rámci projektu a tyto segmenty nahraje přímo do úložiště replaye. Zrekonstruovanou relaci otevřete v Přehrání → Relace; vede i na analytickou stopu stejné relace.

Poznámka

Replay závisí na vašem tarifu. Kolik relací se zachytí a jak dlouho se uchovávají, závisí na tarifu projektu; u nižších tarifů Kixo stále ukládá odlehčená metadata relace metadata, aby se relace zobrazila v seznamech i analytice.

Feature flagy

Hodnoty flagů za běhu zjistíte přes Kixo.getFeatureFlag().

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

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

Odesílání a chování offline

SDK ukládá události do lokální fronty, odesílá je dávkově a dočasná selhání opakuje s postupně delší prodlevou. Pokud je sběr pozastavený v nastavení projektu, nové události se neodesílají, dokud sběr znovu nepovolíte.

Diagnostika

Snapshot stavu jen pro čtení — hodí se při ladění typu „proč mi netečou události?“ ve vývojářských nástrojích.

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