Web SDK

Kixo Web SDK бір жолдық embed арқылы clicks, page views, sessions, errors, scroll depth, web vitals, rage-clicks, dead-clicks және heatmap деректерін автоматты түрде жинайды. Network request monitoring opt-in параметрі ретінде қолжетімді. Native ES module ретінде таратылады және заманауи браузерлерде жұмыс істейді.

Орнату

Script тегі (CDN)

Үзіндіні жабылатын </head> тегінің алдына қосыңыз. type="module" мәніне назар аударыңыз — SDK ES модулі болғандықтан, бұл міндетті. Session replay коды бөлек жүктеледі: replay қосылғаннан кейін ғана нұсқасы сәйкес recorder chunk тартылады. Соның арқасында replay өшірулі кезде негізгі bundle шағын болып қалады.

html

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

Ескерту

SDK script URL-ден project_id және api_key мәндерін оқып, өзін инициализациялайды. Параметрлерді қолданба кодында баптағыңыз келсе, 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 арқылы емес, қолданба кодында баптағыңыз келсе, осыны пайдаланыңыз. Ол CDN embed-тегідей Kixo API-ын береді.

bash

npm install @kixo.io/web

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

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

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

Егер Lovable, Bolt, v0 немесе Replit сияқты AI-powered builder қолданып жатсаңыз, script-tag үзіндісін builder ішіндегі chat не code-injection баптауларына тікелей қойыңыз. Көп builder сайттың <head> бөлігіне скрипт қосуды қолдайды.

Баптау

Екі жолдық embed төмендегі жергілікті analytics әдепкі мәндерін қолданады. Request monitoring әлі де opt-in күйінде қалады. Session replay әдейі Kixo.init() ішіне кірмейді: оны қосу, sampling, privacy, duration және түсіру баптаулары тек project 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 — network tracking қосулы болса, сұраулар уақыты туралы қосымша дерек
heatmap_click / scroll — heatmap деректері

Толық тізімді Оқиғалар анықтамалығы бөлімінен қараңыз.

Custom оқиғалар

Kixo.track()

Қажет болса, properties-пен бірге custom оқиға жіберіңіз.

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

Типтелген оқиға көмекшілері

Kixo атауы бойынша танитын оқиғалар үшін Kixo.track() үстіндегі ыңғайлы қабат (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Typed wrapper-лер properties-ті compile-time кезінде тексереді және кілт атаулары үшін бір ғана шындық көзін береді — backend-тегі standard-event detector атауларды дәлме-дәл салыстырады.

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

Ағымдағы құрылғыны белгілі пайдаланушымен байланыстырыңыз. Резервтелген стандарт property кілттері $ префиксімен беріледі (Mixpanel дәстүрі), сондықтан олар өзіңіздің custom trait-теріңізден бөлек тұрады және dashboard-тағы профиль бағандарына шығарылады — толық 37 кілт тізімі үшін төмендегі Стандартты property каталогы бөлімін қараңыз.

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 науқандарында немесе chat сұрауларында нысаналау үшін пайдаланушыны тег етудің ең таза жолы — boolean түрі.

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

Properties қайта жүктеулер арасында localStorage ішінде сақталады және кейінгі оқиғаларға автоматты түрде қосылады. Оларды chat-та "subscribe мәні true болатын пайдаланушыларға email науқанын құр" сияқты prompt-пен пайдаланыңыз — Kixo сегментті құрып, шаблон нобайын автоматты түрде дайындайды. Kixo.reset() кезінде тазартылады.

Kixo.group()

Пайдаланушыны компаниямен не ұйыммен байланыстырыңыз.

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

Kixo.reset()

Identity, super-properties және сақталған кезекті тазалаңыз. Кейінгі оқиғалар алдыңғы пайдаланушыға телінбеуі үшін мұны logout кезінде шақырыңыз.

Kixo.reset();

Стандартты property каталогы

Резервтелген property кілттері $ префиксімен беріледі, сондықтан олар custom traits-пен бір атау кеңістігінде қақтығыспайды. Kixo каталогында 3 әмбебап pack (identity, geo, lifecycle) және 5 B2B салалық pack (subscription, e-commerce, media, marketplace, loyalty) бойынша 37 кілт бар. Өніміңізге сәйкес келетіндерін ғана орнатыңыз — дашборд соған бейімделіп, тек толтырылған pack-терді көрсетеді.

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

Әрдайым қажет. Профиль тақырыбындағы бағандарды орнатады.

Кілт	Түрі	Сипаттама
`$email`	жол	Негізгі email, көбіне identity stitching үшін біріктіру кілті ретінде қолданылады.
`$phone`	жол	E.164 форматындағы телефон нөмірі.
`$name`	жол	Көрсетілетін толық аты.
`$first_name`	жол	Аты.
`$last_name`	жол	Тегі.
`$avatar_url`	жол	Пайдаланушының аватар суретіне апаратын толық URL.

Гео

Географиялық контекст.

Кілт	Түрі	Сипаттама
`$country`	жол	ISO 3166 ел коды.
`$city`	жол	Қала атауы.
`$region`	жол	Штат немесе провинция.
`$timezone`	жол	`America/Los_Angeles` сияқты IANA уақыт белдеуі.
`$language`	жол	`en` немесе `ru-RU` сияқты IETF тегі.
`$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	Ағымдағы жазылым басталған уақыт.

E-commerce

Өнім сатсаңыз, орнатыңыз.

Кілт	Түрі	Сипаттама
`$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`	жол	VIP деңгейінің slug-ы.
`$referral_count`	сан	Осы пайдаланушыға тиесілі сәтті жолдамалар саны.

Кеңес

Өзіңіздің үлгіңізді көрмей тұрсыз ба? Custom trait-тер үшін жай кілттерді қолданыңыз. Олар dashboard-тағы Custom Traits панелінде көрінеді де, профиль бағандарын былғамайды. Жоғарыдағы 5 тік pack — B2B өнімдерінде жиі кездесетін үлгілерге негізделген жорамалдар; клиентке тән атаулар (мысалы, shipping_plan) жалаң кілт күйінде қалады.

Super-properties

Сыртқа жіберілетін әр оқиғаға автоматты түрде қосылатын, сессияға тән key/value жұптары. Олар identify() traits-тен өзгеше: traits identity-ді сипаттайды, ал super-properties сессия контекстін береді — белсенді A/B нұсқасы, build түрі, қосылған feature flag-тер, серіктестік ref. Қайта жүктеулер арасында localStorage ішінде сақталады, reset() кезінде тазартылады. Кілт қақтығысса, track() ішіндегі оқиғаға тән properties әрқашан басым болады.

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

Жылу карталары

Heatmap жазу әдепкіде қосулы: шертулер мен scroll тереңдігі екеуі де 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 снапшоты мен өзгерістер ағынын жазады. Соның арқасында дашборд бетті оқиғалар ізімен қатар, таймлайнда жылжытып көруге болатын сессия ретінде қайта құрастырады. Бұл экран видеосын жазу емес, DOM-ды қайта құрастыру. Replay Әдепкіде өшірулі. Оны жоба үшін Басқару тақтасы → Баптаулар → Сессияны қайта ойнату бөлімінде қосыңыз; қолданба кодын өзгерту қажет емес. Replay қосылғаннан кейін recorder нұсқасы сәйкес келетін бөлек chunk-тен жүктеледі.

Ескерту

Негізгі шындық көзі — дашборд. Enable replay, Mask inputs, ең ұзақ ұзақтығын және кеңейтілген capture басқару тетіктерін сол жерден орнатыңыз. captureOnCellular да iOS және Android үшін сол жоба саясатының ішінде сақталады; браузерлер Wi‑Fi мен ұялы желіні сенімді ажырата алмайды, сондықтан Web SDK бұл тек native ортаға тән шектеуді хабарлап, елемейді.

Не бүркемеленеді

Replay-ді қауіпсіз қосуға болатындай етіп жасадық. Сезімтал контентті әдепкіде қосулы үш қорғаныс қабаты қорғайды:

Енгізу өрістерін бүркемелеу жоба деңгейінде басқарылады — Dashboard-тағы Енгізу өрістерін бүркемелеу параметрі қосулы кезде (әдепкі күйі), терілген таңбалар браузерден шықпай тұрып жұлдызшаларға ауыстырылады. Оны тек нақты, сезімталдығы төмен қажеттілік үшін өшіріңіз; identity, authentication және payment өрістері бәрібір бүркемеленеді.
data-kixo-mask атрибуты элементті және оның бүкіл ішкі тармағын бұғаттайды. Оны жеке не құпия дерек болуы мүмкін кез келген контейнерге қойыңыз; replay-де сол тармақтың мәтіні мен DOM мазмұнының орнына placeholder ғана қалады.
html
```
<div data-kixo-mask>
  
  
</div>
```
Сезімтал өрістер әрдайым бүркемеленеді — password, card number, CVV, SSN, secret немесе token сияқты көрінетін енгізу өрістері (type, name, id немесе autocomplete бойынша) жобаңыздағы Енгізу өрістерін бүркемелеу параметрі өшірулі болса да бүркемеленеді. Экранда көрінетін мәтін мен сериалданған DOM атрибуттары да жүктеп жіберу алдында Kixo ішіндегі PII сүзгісінен өтеді.

Деректерді жинау

SDK интеграцияңыз бен жоба баптауларында қосылған трекерлерді, сондай-ақ қолданба жіберетін оқиғалар мен properties-ті жинайды.

Жазбалар қайда сақталады

SDK rrweb оқиғаларын көлемі шектеулі сегменттерге gzip-пен қысады, Kixo-дан жобаға байланған signed upload URL сұрайды да, сол сегменттерді replay storage-қа тікелей жүктейді. Қайта құрастырылған сессияны Replay → Сессиялар бөлімінен ашыңыз; онда осы сессияның analytics ізіне сілтеме бар.

Ескерту

Replay қолжетімділігі тариф жоспарыңызға байланысты. Қанша сессия жазылатыны және қанша уақыт сақталатыны жобаңыздың тарифіне байланысты; төменгі деңгейлерде де Kixo жеңіл session метадеректер жазады, сондықтан сессия тізімдерде және аналитикада көрінеді.

Функция жалаушалары

Жалау мәндерін орындау кезінде Kixo.getFeatureFlag() арқылы тексеріңіз.

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

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

Жеткізу және офлайн режимдегі жұмыс

SDK оқиғаларды құрылғыда кезекке жинайды, оларды топтап жібереді және уақытша қателер болса, backoff-пен қайта жібереді. Егер жинау project settings арқылы тоқтатылса, collection қайта қосылғанша жаңа оқиғалар жіберілмейді.

Диагностика

Тек оқуға арналған күй снапшоты — dev tools-та «оқиғаларым неге жіберілмей жатыр?» дегенді тексеруге ыңғайлы.

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