Web SDK

Kixo Web SDK автоматично проследява кликвания, прегледи на страници, сесии, грешки, дълбочина на скролиране, web vitals, rage-clicks, dead-clicks и данни за топлинни карти само с едноредово вграждане. Наблюдението на мрежовите заявки е налично като настройка по избор. Разпространява се като native ES module и работи в съвременни браузъри.

Инсталиране

Script tag (CDN)

Добавете снипета преди затварящия таг </head>. Обърнете внимание на type="module" — задължително е, защото SDK е ES модул. 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 адреса на скрипта. Предоставя същия Kixo API като вграждането през CDN.

bash

npm install @kixo.io/web

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

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

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

Ако изграждате с AI-powered builder като Lovable, Bolt, v0 или Replit, поставете снипета със 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 могат да изключват локалните аналитични тракери. 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 и да се показват в колоните на профила в 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() — маркира потребител за сегментиране

Добавете произволни атрибути ключ/стойност към текущия потребител. Стойностите могат да бъдат низове, числа или булеви стойности — булевата стойност е най-чистият начин да етикет потребител за по-късно таргетиране в сегменти, имейл кампании или заявки в чата.

// 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 между презарежданията и автоматично се добавят към следващите събития. Можете да ги използвате в чата с подкани като „създай имейл кампания за потребители, при които 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 вертикални пакета (абонамент, електронна търговия, медии, маркетплейс, лоялност). Задайте само тези, които са приложими за продукта ви — таблото се адаптира и показва само пакетите, които попълвате.

Идентичност

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

Ключ	Тип	Описание
`$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 в dashboard-а, без да запълват колоните на профила. Петте вертикални пакета по-горе са целенасочени предположения за най-често срещаните B2B модели — специфичната за клиента терминология (например shipping_plan) остава без префикс.

Суперсвойства

Ключ/стойност двойки за сесията, които автоматично се добавят към всяко изходящо събитие. За разлика от traits в identify(), които описват идентичността, super-properties описват контекста на сесията — активен A/B вариант, вариант на build, включени feature flags, affiliate референт. Съхраняват се в 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 е изключено по подразбиране. Включете го за проекта от Табло → Настройки → Запис на сесии; не е нужна промяна в кода на приложението. След включване записващият модул се зарежда от отделен chunk със същата версия.

Забележка

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

Какво се маскира

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

Маскирането на полетата се управлява от проекта — когато настройката Маскиране на полета в Dashboard е включена (по подразбиране), въведените знаци се заменят със звездички, преди да напуснат браузъра. Изключвайте я само при конкретна нужда с ниска чувствителност на данните; полетата за самоличност, удостоверяване и плащане остават маскирани.
Атрибутът data-kixo-mask скрива елемент и цялото му поддърво. Поставяйте го на всеки контейнер, който може да съдържа лични или поверителни данни; в записа се вижда заместител, а не текстът или DOM съдържанието на това поддърво.
html
```
<div data-kixo-mask>
  
  
</div>
```
Чувствителните полета винаги се маскират — полета за въвеждане, които приличат на password, номер на карта, CVV, SSN, secret или token (по type, name, id или autocomplete), се маскират дори когато настройката Маскиране на полета на проекта е изключена. Видимият текст и сериализираните атрибути на DOM също минават през PII филтъра на Kixo преди качване.

Събиране на данни

SDK записва тракерите, включени в настройките на интеграцията и проекта, както и събитията и свойствата, които приложението ви изпраща.

Къде отиват записите

SDK компресира rrweb събитията с gzip в сегменти с ограничен размер, заявява от Kixo подписан URL за качване в рамките на проекта и качва тези сегменти директно в хранилището за replay. Отворете възстановената сесия в Replay → Сесии; оттам има връзка към аналитичната следа на същата сесия.

Забележка

Replay зависи от плана ви. Колко сесии се заснемат и съхраняват зависи от плана на проекта; при по-ниските нива Kixo все пак записва олекотени метаданни за сесията, така че тя да се вижда в списъците и аналитиката.

Функционални флагове

Проверявайте стойностите на флаговете по време на изпълнение чрез Kixo.getFeatureFlag().

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

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

Изпращане и поведение офлайн

SDK поставя събитията в локална опашка, изпраща ги на партиди и повтаря временните неуспехи с backoff. Ако събирането е спряно от настройките на проекта, новите събития не се изпращат, докато не бъде включено отново.

Диагностика

Снимка на състоянието само за четене — полезна при диагностика в инструментите за разработчици, когато се питате „защо събитията ми не пристигат?“.

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