Web SDK

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

Установка

Тег script (CDN)

Добавьте snippet перед закрывающим тегом </head>. Обратите внимание на type="module": это обязательно, потому что SDK поставляется как ES-модуль. Запись сессий вынесена в отдельный 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-конструкторе вроде Lovable, Bolt, v0 или Replit, вставьте snippet со script-тегом прямо в чат конструктора или в настройки вставки кода. Большинство таких конструкторов умеют добавлять скрипты в <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 можно отключать локальные аналитические трекеры. У воспроизведения сессий вообще нет локального флага принудительного включения: настройте его в 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() — пометить пользователя для сегментации

Добавьте текущему пользователю произвольные атрибуты в формате ключ/значение. Значениями могут быть строки, числа или булевы значения; булево значение — самый простой и чистый способ тег пользователя для дальнейшего таргетинга в сегментах, 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()

Очищает identity, super-properties и сохранённую очередь. Вызывайте при logout, чтобы следующие события не привязывались к предыдущему пользователю.

Kixo.reset();

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

Зарезервированные ключи свойств используют префикс $, чтобы не пересекаться с вашими пользовательскими traits. В каталоге Kixo — 37 ключей: 3 универсальных набора (identity, geo, lifecycle) и 5 отраслевых наборов для B2B (subscription, e-commerce, media, marketplace, loyalty). Задавайте только те, что подходят вашему продукту, — в дашборде будут показаны только заполненные наборы.

Идентификация

Используется всегда. Задаёт колонки в заголовке профиля.

Ключ	Тип	Описание
`$email`	строка	Основной 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`	число	Успешные рефералы, засчитанные этому пользователю.

Совет

Не нашли подходящий вариант? Используйте обычные ключи для пользовательских 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, чтобы дашборд мог восстановить страницу как сессию с перемоткой рядом с лентой событий. Это реконструкция DOM, а не видеозапись экрана. Replay по умолчанию выключено. Включите его для проекта в разделе Панель управления → Настройки → Повтор сеанса; код приложения менять не нужно. После включения рекордер загружается отдельным чанком с той же версией.

Примечание

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

Что маскируется

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

Маскирование ввода задаётся на уровне проекта — пока в Dashboard включена настройка Маскировать ввод (по умолчанию она включена), введённые символы заменяются звёздочками ещё до отправки из браузера. Отключайте её только для конкретных сценариев с низкой чувствительностью данных; поля identity, authentication и payment всё равно остаются замаскированы.
Атрибут data-kixo-mask скрывает элемент и всё его поддерево. Ставьте его на любой контейнер, в котором может быть личный или конфиденциальный контент: в воспроизведении будет показан заполнитель, а не текст или содержимое DOM из этого поддерева.
html
```
<div data-kixo-mask>
  
  
</div>
```
Чувствительные поля маскируются всегда — поля, похожие на пароль, номер карты, 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 ставит события в локальную очередь, отправляет их пакетами и повторяет попытки при временных сбоях с увеличивающейся задержкой. Если сбор данных приостановлен в настройках проекта, новые события не отправляются, пока вы не включите его снова.

Диагностика

Снимок состояния только для чтения — полезен для отладки в dev tools, когда нужно понять, почему события не отправляются.

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

Web SDK

Установка

Тег script (CDN)

npm

No-Code-платформы

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

Автоматически отслеживаемые события

Пользовательские события

Kixo.track()

Типизированные хелперы событий

Kixo.identify()

Kixo.setUserProperty() — пометить пользователя для сегментации

Kixo.group()

Kixo.reset()

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

Идентификация

Геоданные

Жизненный цикл

Подписка

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

Медиа

Маркетплейс

Лояльность

Super-properties

Тепловые карты

Запись сессий

Что маскируется

Сбор данных

Куда попадают записи

Флаги функций

Отправка данных и работа офлайн

Диагностика