Web SDK

Kixo Web SDK со еднолиниско вметнување автоматски следи кликови, прегледи на страници, сесии, грешки, длабочина на скролање, web vitals, rage-clicks, dead-clicks и податоци за heatmap. Следењето мрежни барања е достапно како опционална поставка. Се испорачува како природен ES модул и работи во современи прелистувачи.

Инсталација

Script tag (CDN)

Додајте го snippet-от пред затворачкиот </head> tag. Забележете го type="module" — задолжително е бидејќи SDK е ES module. Session replay е поделен во version-matched 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 од script 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

Користете го ова кога сакате да ги конфигурирате опциите во кодот на апликацијата наместо преку script 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, вметнете го snippet-от со script tag директно во chat-от на алатката или во нејзините settings за вбризгување код. Повеќето builders поддржуваат додавање скрипти во <head> на вашата страница.

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

Дволиниското вметнување ги користи локалните стандардни analytics поставки подолу. Следењето барања останува опционално. 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 за Конфигурација контролирана од проектот. можат да ги исклучат локалните аналитички trackers. 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). Typed wrappers даваат валидација на својства при компајлирање и едно место за вистината за имињата на клучевите — backend-скиот детектор за стандардни настани совпаѓа дословно.

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

Поврзете го тековниот уред со познат корисник. Reserved standard property keys носат префикс $ (Mixpanel convention) за да бидат именски одвоени од вашите custom traits и да се појавуваат во колоните на профилот во аналитичкиот панел — видете го Стандарден каталог на својства подолу за целосната листа од 37 keys.

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 формата е најчист начин да ознака корисник за подоцнежно таргетирање во segments, email campaigns или chat queries.

// 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 is true" — Kixo автоматски составува сегмент и подготвува шаблон. Се бришат на Kixo.reset().

Kixo.group()

Поврзете го корисникот со компанија или организација.

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

Kixo.reset()

Исчистете ги identity, super-properties и зачуваната queue. Повикајте го ова при logout за следните настани да не му се припишуваат на претходниот корисник.

Kixo.reset();

Стандарден каталог на својства

Резервираните клучеви на својства имаат префикс $, за да бидат одвоени од вашите сопствени traits. Каталогот на Kixo опфаќа 37 клучеви во 3 универзални пакети (идентитет, гео, животен циклус) и 5 вертикални B2B пакети (претплата, е-трговија, медиуми, пазар, лојалност). Поставете ги само оние што важат за вашиот производ — контролниот панел се приспособува и ги прикажува само пакетите што ги пополнувате.

Identity

Секогаш е релевантно. Ги поставува колоните во заглавјето на профилот.

Клуч	Тип	Опис
`$email`	низа	Примарна е-пошта, често клучот за спојување при поврзување идентитети.
`$phone`	низа	Телефонски број во E.164 формат.
`$name`	низа	Целосно прикажано име.
`$first_name`	низа	Име.
`$last_name`	низа	Презиме.
`$avatar_url`	низа	Целосна URL до сликата за аватар на корисникот.

Geo

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

Клуч	Тип	Опис
`$country`	низа	Код на држава според ISO 3166.
`$city`	низа	Име на град.
`$region`	низа	Сојузна држава или провинција.
`$timezone`	низа	IANA зона како `America/Los_Angeles`.
`$language`	низа	IETF tag како `en` или `ru-RU`.
`$locale`	низа	Целосен идентификатор на 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 или низа	Категории што ги следи корисникот.
`$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`	број	Успешни препораки припишани на овој корисник.

Совет

Не го гледате вашиот шаблон? Користете bare keys за custom traits. Тие се појавуваат во панелот Custom Traits во аналитичкиот панел без да ги полнат колоните на профилот. Петте вертикални пакети погоре се насочени претпоставки за најчестите B2B модели — customer-specific terminology (на пр. shipping_plan) останува bare.

Super-properties

Парови клуч/вредност по сесија што автоматски се прикачуваат на секој излезен настан. Се разликуваат од identify() traits (кои го опишуваат идентитетот); super-properties го опишуваат контекстот на сесијата — активна A/B варијанта, тип на build, вклучени feature flags, affiliate ref. Се чуваат во 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 %. Движењето на глувчето е opt-in (создава голем обем; вклучувајте го по страница ако има корист).

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

Репродукција на сесија

Session replay снима rrweb DOM snapshot и stream од промени, за контролниот панел да може да ја реконструира страницата како сесија што може да се прегледува покрај трагата од настани. Ова е DOM реконструкција, а не видео-снимка од екранот. Replay е исклучено по правило. Вклучете го за проектот во Контролна табла → Поставки → Снимање на сесии; не е потребна промена во кодот на апликацијата. Кога е вклучен, recorder-от се презема од посебен chunk со усогласена верзија.

Забелешка

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

Што се маскира

Replay е направен да биде безбеден за вклучување. Чувствителната содржина ја штитат три слоја, и сите се вклучени по правило:

Маскирањето на внесот се контролира на ниво на проект — додека поставката Маскирај внесови во Dashboard е вклучена (стандардно), внесените знаци се заменуваат со ѕвездички пред да го напуштат прелистувачот. Исклучувајте ја само за конкретна потреба со ниска чувствителност; полињата за идентитет, автентикација и плаќање остануваат маскирани.
Атрибутот data-kixo-mask блокира елемент и целото негово поддрво. Ставете го на кој било контејнер што може да содржи лична или доверлива содржина; снимката ќе содржи placeholder, а не текст или DOM содржина од тоа поддрво.
html
```
<div data-kixo-mask>
  
  
</div>
```
Чувствителните полиња секогаш се маскираат — полиња што личат на password, број на картичка, CVV, SSN, secret или token (според type, name, id или autocomplete) се маскираат дури и кога поставката на проектот Маскирај внесови е исклучена. Видливиот текст и серилизираните DOM атрибути исто така минуваат низ Kixo PII sanitizer пред испраќање.

Собирање податоци

SDK ги снима тракерите што се вклучени во поставките за интеграцијата и проектот, како и настаните и својствата што ги испраќа вашата апликација.

Каде одат снимките

SDK ги компресира rrweb настаните со gzip во ограничени сегменти, бара project-scoped signed upload URL од Kixo и тие сегменти ги прикачува директно во складиштето за replay. Реконструираната сесија отворете ја во Снимања → Сесии; таа е поврзана со аналитичката трага на истата сесија.

Забелешка

Replay зависи од вашиот пакет. Колку сесии се снимаат и задржуваат зависи од пакетот на проектот; на пониските нивоа Kixo сепак снима лесни session метаподатоци за сесијата да се појавува во листите и аналитиката.

Функционални ознаки

Проверете ги вредностите на flag-овите во runtime преку 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);