Web SDK

Kixo Web SDK з аўтаматычным адсочваннем клікаў, праглядаў старонак, сесій, памылак, глыбіні пракруткі, web vitals, rage-clicks, dead-clicks і даных для цеплавой карты праз устаўку ў адзін радок. Маніторынг сеткавых запытаў даступны як опцыя. Пастаўляецца як натыўны модуль ES і працуе ў сучасных браўзерах.

Усталёўка

Тэг script (CDN)

Дадайце фрагмент перад закрывальным тэгам </head>. Звярніце ўвагу на type="module" — гэта абавязкова, бо SDK з’яўляецца ES module. Session replay выдзелены ў асобны recorder chunk з адпаведнай версіяй, які загружаецца толькі пасля ўключэння replay, таму базавы bundle застаецца невялікім, пакуль replay выключаны.

html

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

Заўвага

SDK счытвае project_id і api_key з URL скрыпта і ініцыялізуецца сам. Каб задаваць параметры ў кодзе прыкладання, прыбярыце параметры URL і замест гэтага выклічце Kixo.init({...}) — глабальны аб’ект 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

Выкарыстоўвайце гэта, калі хочаце задаваць параметры ў кодзе прыкладання, а не праз URL скрыпта. Даступны той самы API Kixo, што і ўстаўка праз 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 платформы

Калі вы збіраеце сайт у AI-powered канструктары накшталт Lovable, Bolt, v0 або Replit, устаўце фрагмент са script tag проста ў чат канструктара або ў налады ўстаўкі кода. Большасць такіх канструктараў падтрымлівае даданне скрыптоў у <head> вашага сайта.

Канфігурацыя

Устаўка ў два радкі выкарыстоўвае лакальныя стандартныя налады аналітыкі ніжэй. Маніторынг запытаў па-ранейшаму ўключаецца асобна. Session replay наўмысна не вынесены ў Kixo.init(): яго ўключэнне, семпліраванне, прыватнасць, працягласць і налады збору задаюцца толькі ў 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,
  },

});

Заўвага

Канфігурацыя, якая задаецца на ўзроўні праекта. Налады Dashboard могуць адключаць лакальныя аналітычныя трэкеры. У Replay увогуле няма лакальнага сцяжка прымусовага ўключэння: наладжвайце яго ў Settings → Session replay, і SDK прымяніць актуальную палітыку праекта пры наступным абнаўленні канфігурацыі.

Падзеі, што адсочваюцца аўтаматычна

З канфігурацыяй па змаўчанні Kixo аўтаматычна збірае гэтыя падзеі без дадатковага кода:

page_view — кожная навігацыя (першае адкрыццё + змены маршруту ў SPA)
session_start / session_end
click — усе ўзаемадзеянні з націскам для селектара элемента
scroll_depth — парогі 25 / 50 / 75 / 100 %
rage_click — паўторныя націскі па тым самым элеменце
dead_click — націскі па неінтэрактыўных элементах
error — неперахопленыя выключэнні JavaScript + адхіленыя promise
performance — метрыкі загрузкі старонкі і Web Vitals (LCP, FCP, FID, CLS, INP, TTFB)
network_request — неабавязковыя таймінгі запытаў, калі ўключана адсочванне сеткі
heatmap_click / scroll — даныя цеплавой карты

Поўны спіс глядзіце ў Даведнік па падзеях.

Карыстальніцкія падзеі

Kixo.track()

Адправіць карыстальніцкую падзею з неабавязковымі ўласцівасцямі.

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

Тыпізаваныя хелперы падзей

Сінтаксічны цукар над Kixo.track() для падзей, якія Kixo распазнае па назве (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Тыпізаваныя абгорткі даюць праверку ўласцівасцей на этапе кампіляцыі і адзіную крыніцу праўды для назваў ключоў — дэтэктар стандартных падзей на бэкендзе супастаўляе іх літаральна.

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

Звязвае бягучую прыладу з вядомым карыстальнікам. Зарэзерваваныя стандартныя ключы ўласцівасцей маюць прэфікс $ (канвенцыя Mixpanel), каб не перасякацца з вашымі ўласнымі traits і трапляць у слупкі профілю ў аналітычнай панэлі — поўны спіс з 37 ключоў глядзіце ў Стандартны каталог уласцівасцей ніжэй.

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() — пазначыць карыстальніка для сегментацыі

Дадае адвольныя атрыбуты key/value да бягучага карыстальніка. Значэннямі могуць быць strings, numbers або booleans — форма boolean з’яўляецца самым чыстым спосабам тэг карыстальніка для далейшага таргетынгу ў сегментах, email-кампаніях або запытах у чаце.

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

Уласцівасці захоўваюцца ў localStorage паміж перазагрузкамі і аўтаматычна дадаюцца да наступных падзей. Выкарыстоўвайце іх у chat з запытамі кшталту "стварыць email-кампанію для карыстальнікаў, у якіх subscribe = true" — Kixo сам збярэ сегмент і падрыхтуе шаблон. Ачышчаюцца праз Kixo.reset().

Kixo.group()

Звязвае карыстальніка з кампаніяй або арганізацыяй.

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

Kixo.reset()

Ачышчае identity, super-properties і захаваную чаргу. Выклікайце гэта пры выхадзе з сістэмы, каб наступныя падзеі не прыпісваліся папярэдняму карыстальніку.

Kixo.reset();

Стандартны каталог уласцівасцей

Зарэзерваваныя ключы ўласцівасцей маюць прэфікс $, таму не канфліктуюць з вашымі ўласнымі traits. Каталог Kixo ахоплівае 37 ключоў у 3 універсальных пакетах (ідэнтычнасць, геа, жыццёвы цыкл) і 5 вертыкальных пакетах B2B (падпіска, e-commerce, медыя, маркетплэйс, лаяльнасць). Задавайце толькі тое, што пасуе вашаму прадукту, — dashboard сам адаптуецца і пакажа толькі запоўненыя пакеты.

Identity

Заўсёды актуальна. Задае слупкі ў загалоўку профілю.

Ключ	Тып	Апісанне
`$email`	радок	Асноўны email, часта служыць ключом зліцця для звязвання ідэнтычнасці.
`$phone`	радок	Нумар тэлефона ў фармаце E.164.
`$name`	радок	Поўнае адлюстроўванае імя.
`$first_name`	радок	Імя.
`$last_name`	радок	Прозвішча.
`$avatar_url`	радок	Поўны URL да выявы аватара карыстальніка.

Geo

Геаграфічны кантэкст.

Ключ	Тып	Апісанне
`$country`	радок	Код краіны паводле ISO 3166.
`$city`	радок	Назва горада.
`$region`	радок	Штат або правінцыя.
`$timezone`	радок	IANA zone накшталт `America/Los_Angeles`.
`$language`	радок	IETF tag накшталт `en` або `ru-RU`.
`$locale`	радок	Поўны ідэнтыфікатар лакалі.

Жыццёвы цыкл

Калі мы бачылі гэтага карыстальніка.

Ключ	Тып	Апісанне
`$created`	ISO8601	Час рэгістрацыі або стварэння акаўнта.
`$last_seen`	ISO8601	Час апошняга ўзаемадзеяння.

Падпіска

Задавайце, калі ў вашага прадукту ёсць тарыфныя планы.

Ключ	Тып	Апісанне
`$plan`	радок	Slug тарыфу — `free`, `pro`, `enterprise`.
`$subscription_status`	радок	`active` / `trial` / `cancelled` / `past_due`.
`$trial_ends`	ISO8601	Калі заканчваецца бягучы пробны перыяд.
`$mrr`	лік	Штомесячны рэгулярны даход у валюце акаўнта.
`$subscription_started`	ISO8601	Калі пачалася бягучая падпіска.

Электронная камерцыя

Задавайце, калі прадаяце тавары.

Ключ	Тып	Апісанне
`$lifetime_orders`	лік	Колькасць завершаных заказаў.
`$lifetime_revenue`	лік	Агульныя выдаткі.
`$aov`	лік	Сярэдні чэк.
`$last_purchase`	ISO8601	Апошняя паспяховая пакупка.
`$first_purchase`	ISO8601	Першая паспяховая пакупка.
`$cart_abandoned_count`	лік	Агульная колькасць пакінутых кошыкаў за ўвесь час.

Медыя

Задавайце, калі публікуеце кантэнт.

Ключ	Тып	Апісанне
`$content_tier`	радок	`free` / `premium` / `paid`.
`$subscribed_categories`	CSV string або array	Катэгорыі, за якімі сочыць карыстальнік.
`$watch_time_total`	лік	Агульны час прагляду ў секундах за ўвесь час.
`$last_played`	ISO8601	Апошні запуск прайгравання.

Маркетплэйс

Задавайце, калі ваш прадукт — двухбаковая платформа.

Ключ	Тып	Апісанне
`$seller_tier`	радок	Slug тарыфу на баку прадаўца.
`$buyer_tier`	радок	Slug узроўню на баку пакупніка.
`$listings_count`	лік	Актыўныя аб’явы, якімі валодае карыстальнік.
`$reviews_count`	лік	Водгукі, якія атрымаў карыстальнік.
`$verified`	boolean	Статус KYC.

Лаяльнасць

Задавайце для праграм узаемадзеяння і ўзнагарод.

Ключ	Тып	Апісанне
`$loyalty_points`	лік	Бягучы баланс даступных для выкарыстання балаў.
`$vip_level`	радок	Slug узроўню VIP.
`$referral_count`	лік	Паспяховыя рэфералы, аднесеныя да гэтага карыстальніка.

Парада

Не бачыце свайго шаблону? Выкарыстоўвайце простыя ключы для custom traits. Яны з’явяцца ў панэлі Custom Traits у аналітычнай панэлі і не будуць засмечваць слупкі профілю. Пяць вертыкальных набораў вышэй — гэта практычныя здагадкі для самых тыповых формаў у B2B; спецыфічная для кліента тэрміналогія (напрыклад, shipping_plan) застаецца без прэфіксаў.

Super-properties

Пары ключ/значэнне на ўзроўні сесіі, якія аўтаматычна дадаюцца да кожнай выходнай падзеі. У адрозненне ад traits identify() (яны апісваюць асобу), super-properties апісваюць кантэкст сесіі — актыўны варыянт A/B, варыянт зборкі, уключаныя feature flags, партнёрскую спасылку. Захоўваюцца ў localStorage паміж перазагрузкамі; ачышчаюцца праз reset(). Калі ключы супадаюць, перавагу заўсёды маюць properties для канкрэтнай падзеі ў 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();

Цеплавыя карты

Запіс цеплавой карты ўключаны па змаўчанні — націскі і глыбіня пракруткі, абодва з выбаркай 100 %. Адсочванне руху мышы ўключаецца асобна (вялікі аб’ём даных; уключайце для асобных старонак, калі гэта сапраўды трэба).

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

Прайграванне сесій

Session replay запісвае DOM-здымак rrweb і паток змяненняў, каб dashboard мог аднавіць старонку як сесію з пракруткай побач са следам падзей. Гэта аднаўленне DOM, а не відэазапіс экрана. Replay — выключана па змаўчанні. Уключыце яго для праекта ў Панэль кіравання → Налады → Паўтор сесіі; змяняць код прыкладання не трэба. Пасля ўключэння рэкордэр падцягваецца асобным chunk з адпаведнай версіяй.

Заўвага

Dashboard — крыніца праўды. Там задаюцца Enable replay, Mask inputs, максімальная працягласць і пашыраныя элементы кіравання захопам. captureOnCellular захоўваецца ў той жа палітыцы праекта для iOS і Android; браўзеры не даюць надзейнага сігналу пра Wi‑Fi ці сотавую сетку, таму Web SDK паведамляе пра гэта і ігнаруе гэтае абмежаванне, даступнае толькі ў native-асяроддзі.

Што маскіруецца

Replay спраектаваны так, каб яго было бяспечна ўключаць. Адчувальныя даныя абараняюцца трыма ўзроўнямі, і ўсе яны ўключаны па змаўчанні:

Маскіраванне палёў уводу задаецца на ўзроўні праекта — пакуль у Dashboard уключана настройка Маскіраваць палі ўводу (па змаўчанні), уведзеныя сімвалы замяняюцца зорачкамі яшчэ да выхаду з браўзера. Выключайце яе толькі для канкрэтнай задачы з нізкай адчувальнасцю; палі ідэнтыфікацыі, аўтэнтыфікацыі і аплаты ўсё роўна застаюцца замаскіраванымі.
Атрыбут data-kixo-mask блакуе элемент і ўсё яго паддрэва. Стаўце яго на любы кантэйнер, які можа ўтрымліваць асабістыя або канфідэнцыйныя даныя; у паўторы будзе запаўняльнік, а не тэкст або DOM-змесціва гэтага паддрэва.
html
```
<div data-kixo-mask>
  
  
</div>
```
Адчувальныя палі заўсёды маскіруюцца — палі, падобныя да password, card number, CVV, SSN, secret або token (паводле type, name, id або autocomplete), маскіруюцца, нават калі ў праекце выключана настройка Маскіраваць палі ўводу. Бачны тэкст і серыялізаваныя атрыбуты DOM таксама праходзяць праз санітайзер PII у Kixo перад адпраўкай.

Збор даных

SDK збірае трэкеры, уключаныя ў наладах інтэграцыі і праекта, а таксама падзеі і ўласцівасці, якія адпраўляе ваша прыкладанне.

Куды трапляюць запісы

SDK сціскае падзеі rrweb у абмежаваныя сегменты праз gzip, запытвае ў Kixo падпісаны URL для загрузкі ў межах праекта і наўпрост загружае гэтыя сегменты ў сховішча replay. Аднаўленую сесію можна адкрыць у Паўтор → Сесіі; там ёсць спасылка на аналітычны след той самай сесіі.

Заўвага

Replay даступны ў межах вашага плана. Колькасць сеансаў, якія захопліваюцца і захоўваюцца, залежыць ад плана праекта; на малодшых тарыфах Kixo усё адно запісвае лёгкія session метаданыя, каб сеанс быў бачны ў спісах і аналітыцы.

Флагі функцый

Правярайце значэнні флагаў падчас выканання праз Kixo.getFeatureFlag().

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

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

Дастаўка і паводзіны ў афлайне

SDK трымае падзеі ў лакальнай чарзе, адпраўляе іх пакетамі і паўтарае часовыя збоі з backoff. Калі збор спынены ў наладах праекта, новыя падзеі не адпраўляюцца, пакуль яго зноў не ўключаць.

Дыягностыка

Здымак стану толькі для чытання — зручны для адладкі ў dev tools, калі трэба зразумець: «чаму мае падзеі не паступаюць?»

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