Web SDK

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

Встановлення

Тег script (CDN)

Додайте фрагмент перед закривальним тегом </head>. Зверніть увагу на type="module": це обов’язково, бо SDK є ES-модулем. Session replay винесено в окремий recorder chunk із відповідною версією, який завантажується лише після ввімкнення replay, тож базовий бандл залишається малим, доки 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',
});

Платформи без коду

Якщо ви збираєте продукт в AI-конструкторі на кшталт Lovable, Bolt, v0 або Replit, вставте фрагмент зі script tag прямо в чат конструктора або в налаштування вставки коду. Більшість таких платформ підтримують додавання скриптів у <head> вашого сайту.

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

Дворядкова вставка використовує локальні стандартні параметри аналітики, наведені нижче. Моніторинг запитів, як і раніше, вмикається окремо. Session replay навмисно не налаштовується через Kixo.init(): його ввімкнення, вибірка, приватність, тривалість і параметри запису задаються лише в дашборді проєкту.

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), щоб не перетинатися з вашими власними атрибутами й потрапляти до стовпців профілю в Dashboard — повний список із 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. Значеннями можуть бути рядки, числа або булеві значення; булеве значення — найзручніший спосіб тег користувача для подальшого таргетингу в сегментах, 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 між перезавантаженнями й автоматично додаються до наступних подій. Використовуйте їх у чаті з підказками на кшталт "створити email-кампанію для користувачів, у яких subscribe = true" — Kixo автоматично збере сегмент і підготує чернетку шаблону. Очищаються через Kixo.reset().

Kixo.group()

Пов’язує користувача з компанією або організацією.

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

Kixo.reset()

Очистьте ідентифікатор, super-properties і збережену чергу. Викликайте це під час виходу з акаунта, щоб наступні події не приписувалися попередньому користувачеві.

Kixo.reset();

Каталог стандартних властивостей

Зарезервовані ключі властивостей мають префікс $, щоб не перетинатися з вашими власними атрибутами. У каталозі Kixo є 37 ключів у 3 універсальних наборах (ідентичність, геодані, життєвий цикл) і 5 галузевих наборах для B2B (підписка, e-commerce, медіа, маркетплейс, лояльність). Заповнюйте лише ті, що підходять вашому продукту, — дашборд сам підлаштується й покаже тільки використані набори.

Ідентифікація

Завжди актуально. Визначає стовпці в заголовку профілю.

Ключ	Тип	Опис
`$email`	рядок	Основна електронна адреса; часто використовується як ключ злиття для зшивання ідентичностей.
`$phone`	рядок	Номер телефону у форматі E.164.
`$name`	рядок	Повне відображуване ім’я.
`$first_name`	рядок	Ім’я.
`$last_name`	рядок	Прізвище.
`$avatar_url`	рядок	Повний URL зображення аватара користувача.

Геодані

Географічний контекст.

Ключ	Тип	Опис
`$country`	рядок	Код країни за ISO 3166.
`$city`	рядок	Назва міста.
`$region`	рядок	Штат або область.
`$timezone`	рядок	Часовий пояс IANA, наприклад `America/Los_Angeles`.
`$language`	рядок	Тег IETF, наприклад `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-рядок або масив	Категорії, за якими стежить користувач.
`$watch_time_total`	число	Загальний час перегляду в секундах.
`$last_played`	ISO8601	Останній запуск відтворення.

Маркетплейс

Використовуйте, якщо у вас двостороння платформа.

Ключ	Тип	Опис
`$seller_tier`	рядок	Slug рівня на боці продавця.
`$buyer_tier`	рядок	slug рівня на боці покупця.
`$listings_count`	число	Активні оголошення користувача.
`$reviews_count`	число	Відгуки, які отримав користувач.
`$verified`	булеве значення	Статус KYC.

Лояльність

Використовуйте для програм залучення та винагород.

Ключ	Тип	Опис
`$loyalty_points`	число	Поточний баланс балів, доступних до використання.
`$vip_level`	рядок	Slug рівня VIP.
`$referral_count`	число	Успішні реферали, зараховані цьому користувачу.

Порада

Не бачите свого варіанта? Для власних атрибутів використовуйте звичайні ключі без префікса. Вони з’являться в панелі Custom Traits у Dashboard і не засмічуватимуть стовпці профілю. П’ять вертикальних наборів вище — це практичні припущення про найтиповіші B2B-сценарії; специфічна для клієнта термінологія (наприклад, shipping_plan) лишається без префікса.

Супервластивості

Пари ключ/значення на рівні сесії, які автоматично додаються до кожної вихідної події. На відміну від атрибутів 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, щоб дашборд міг відновити сторінку як сесію з перемотуванням поруч із хронологією подій. Це реконструкція DOM, а не відеозапис екрана. Replay вимкнено за замовчуванням. Увімкніть його для проєкту в Панель керування → Налаштування → Повтор сеансу; змінювати код застосунку не потрібно. Після ввімкнення рекордер завантажується окремим чанком із відповідною версією.

Примітка

Дашборд — джерело правди. Там можна налаштувати Enable replay, Mask inputs, максимальну тривалість і розширені параметри запису. captureOnCellular зберігається в тій самій політиці проєкту для iOS і Android; браузери не дають надійного сигналу, чи це Wi‑Fi, чи мобільна мережа, тому Web SDK повідомляє про це нативне обмеження й не застосовує його.

Що маскується

Replay спроєктовано так, щоб його можна було безпечно вмикати. Чутливий вміст захищають три рівні, і всі вони ввімкнені за замовчуванням:

Маскування введення задається на рівні проєкту — коли в Dashboard увімкнено параметр Маскувати введення (типове значення), введені символи замінюються на зірочки ще до виходу з браузера. Вимикайте його лише для конкретних сценаріїв із низькою чутливістю даних; поля ідентифікації, автентифікації та оплати все одно маскуються.
Атрибут data-kixo-mask блокує елемент і все його піддерево. Додавайте його до будь-якого контейнера, що може містити персональні або конфіденційні дані: у replay буде показано заповнювач замість тексту та вмісту 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 все одно зберігає полегшені дані сесії метадані, щоб сесія потрапляла до списків і аналітики.

Прапорці функцій

Перевіряйте значення прапорців під час виконання через 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);