Web SDK

Kixo Web SDK gjurmon automatikisht klikimet, shikimet e faqeve, sesionet, gabimet, thellësinë e lëvizjes, web vitals, rage-clicks, dead-clicks dhe të dhënat e hartës së nxehtësisë me një integrim me një rresht. Monitorimi i kërkesave në rrjet ofrohet si cilësim opt-in. Shpërndahet si modul ES vendas dhe funksionon në shfletues modernë.

Instalimi

Tag-u script (CDN)

Shtoje fragmentin para tag-ut mbyllës </head>. Vër re type="module" — kërkohet sepse SDK është një modul ES. Session replay ndahet në kod si një chunk regjistruesi me version të përputhur, i cili ngarkohet vetëm pasi replay të jetë aktivizuar, kështu që bundle-i bazë mbetet i vogël kur replay është i çaktivizuar.

html

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

Shënim

SDK lexon project_id dhe api_key nga URL-ja e script-it dhe inicializohet vetë. Nëse do t’i konfigurosh opsionet në kodin e aplikacionit, hiq parametrat nga URL-ja dhe thirr Kixo.init({...}) — objekti global Kixo bëhet i disponueshëm sapo të ngarkohet moduli.

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

Përdore këtë kur do t’i konfigurosh opsionet në kodin e aplikacionit dhe jo përmes URL-së së script-it. Ofron të njëjtën API Kixo si integrimi përmes CDN.

bash

npm install @kixo.io/web

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

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

Platformat No-Code

Nëse po ndërton me një builder të fuqizuar nga AI si Lovable, Bolt, v0 ose Replit, ngjite fragmentin me script tag direkt në chat-in e builder-it ose te cilësimet për injektimin e kodit. Shumica e builder-ëve mbështesin shtimin e script-eve te <head> e sajtit tënd.

Konfigurimi

Integrimi me dy rreshta përdor parazgjedhjet lokale të analitikës më poshtë. Monitorimi i kërkesave mbetet opt-in. Session replay mungon me qëllim nga Kixo.init(): aktivizimi, kampionimi, privatësia, kohëzgjatja dhe cilësimet e regjistrimit kontrollohen vetëm nga dashboard-i i projektit.

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,
  },

});

Shënim

Konfigurim i kontrolluar nga projekti. Cilësimet në Dashboard mund të çaktivizojnë gjurmuesit lokalë të analitikës. Replay nuk ka fare një flag lokal aktivizimi: konfiguroje te Settings → Session replay, dhe SDK ndjek politikën më të fundit të projektit në rifreskimin tjetër të konfigurimit.

Evente të gjurmuara automatikisht

Me konfigurimin e parazgjedhur, Kixo i regjistron automatikisht këto evente pa kod shtesë:

page_view — çdo navigim (ngarkimi fillestar + ndryshimet e rrugës në SPA)
session_start / session_end
click — të gjitha ndërveprimet me klikim për përzgjedhësin e elementit
scroll_depth — pragjet 25 / 50 / 75 / 100 %
rage_click — klikime të përsëritura në të njëjtin element
dead_click — klikime në elemente jo ndërvepruese
error — përjashtime JavaScript të pakapura + promise rejections
performance — metrikat e ngarkimit të faqes dhe Web Vitals (LCP, FCP, FID, CLS, INP, TTFB)
network_request — koha e kërkesës, opsionale, kur gjurmimi i rrjetit është aktiv
heatmap_click / scroll — të dhëna të hartës së nxehtësisë

Shih listën e plotë te Referenca e eventeve.

Evente të personalizuara

Kixo.track()

Dërgo një event të personalizuar me veti opsionale.

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

Ndihmës me tipe për eventet

Shtresë lehtësuese mbi Kixo.track() për eventet që Kixo i njeh nga emri (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Këto mbështjellëse me tipe sjellin verifikim të vetive në compile-time dhe një burim të vetëm të së vërtetës për emrat e çelësave — detektori i eventeve standarde në backend përputhet fjalë për fjalë.

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

Lidhe pajisjen aktuale me një përdorues të njohur. Çelësat standardë të rezervuar të vetive mbajnë prefiksin $ (sipas konventës Mixpanel), që të ndahen nga traits custom të tuat dhe të kalojnë në kolonat e profilit në dashboard — shih Katalogu standard i vetive më poshtë për listën e plotë me 37 çelësa.

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() — etiketo një përdorues për segmentim

Shto atribute arbitrare key/value te përdoruesi aktual. Vlerat mund të jenë string, numra ose booleans — forma boolean është mënyra më e pastër për të etiketë një përdorues për targetim të mëvonshëm në segmente, fushata email ose pyetje në chat.

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

Vetitë ruhen në localStorage edhe pas ringarkimit dhe i bashkëngjiten automatikisht eventeve në vijim. Mund t’i përdorësh në chat me kërkesa si "krijo një fushatë email për përdoruesit ku subscribe është true" — Kixo krijon automatikisht segmentin dhe përgatit draftin e shabllonit. Pastrohen në Kixo.reset().

Kixo.group()

Lidhe përdoruesin me një kompani ose organizatë.

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

Kixo.reset()

Pastro identitetin, super-properties dhe radhën e ruajtur. Thirre në logout që eventet pasuese të mos i atribuohen përdoruesit të mëparshëm.

Kixo.reset();

Katalogu standard i vetive

Çelësat e rezervuar të vetive mbajnë prefiksin $, që të dallohen nga tiparet e tua të personalizuara. Katalogu i Kixo mbulon 37 çelësa në 3 paketa universale (identitet, gjeografi, cikël jete) dhe 5 paketa vertikale B2B (abonim, e-commerce, media, treg, besnikëri). Vendos vetëm ato që vlejnë për produktin tënd — dashboard-i përshtatet dhe shfaq vetëm paketat që ke plotësuar.

Identiteti

Gjithmonë e vlefshme. Përcakton kolonat e header-it të profilit.

Çelës	Lloji	Përshkrimi
`$email`	varg	Email-i kryesor, shpesh çelësi i bashkimit për lidhjen e identitetit.
`$phone`	varg	Numër telefoni E.164.
`$name`	varg	Emri i plotë i shfaqur.
`$first_name`	varg	Emri.
`$last_name`	varg	Mbiemri.
`$avatar_url`	varg	URL-ja e plotë e imazhit të avatarit të përdoruesit.

Geo

Kontekst gjeografik.

Çelës	Lloji	Përshkrimi
`$country`	varg	Kodi i vendit sipas ISO 3166.
`$city`	varg	Emri i qytetit.
`$region`	varg	Shtet ose provincë.
`$timezone`	varg	Zonë IANA si `America/Los_Angeles`.
`$language`	varg	Tag IETF si `en` ose `ru-RU`.
`$locale`	varg	Identifikuesi i plotë i locale-it.

Cikli i jetës

Kur e kemi parë.

Çelës	Lloji	Përshkrimi
`$created`	ISO8601	Koha e regjistrimit ose e krijimit të llogarisë.
`$last_seen`	ISO8601	Koha e ndërveprimit të fundit.

Abonim

Vendose nëse produkti yt ka plane.

Çelës	Lloji	Përshkrimi
`$plan`	varg	Slug-u i nivelit — `free`, `pro`, `enterprise`.
`$subscription_status`	varg	`active` / `trial` / `cancelled` / `past_due`.
`$trial_ends`	ISO8601	Kur skadon prova aktuale.
`$mrr`	numër	Të ardhurat mujore periodike në monedhën e llogarisë.
`$subscription_started`	ISO8601	Kur nisi abonimi aktual.

E-commerce

Vendose nëse shet produkte.

Çelës	Lloji	Përshkrimi
`$lifetime_orders`	numër	Numri i porosive të përfunduara.
`$lifetime_revenue`	numër	Shpenzimi total.
`$aov`	numër	Vlera mesatare e porosisë.
`$last_purchase`	ISO8601	Blerja e fundit e suksesshme.
`$first_purchase`	ISO8601	Blerja e parë e suksesshme.
`$cart_abandoned_count`	numër	Numri total i braktisjeve të shportës.

Media

Vendose nëse publikon përmbajtje.

Çelës	Lloji	Përshkrimi
`$content_tier`	varg	`free` / `premium` / `paid`.
`$subscribed_categories`	String CSV ose array	Kategoritë që ndjek përdoruesi.
`$watch_time_total`	numër	Koha totale e shikimit në sekonda.
`$last_played`	ISO8601	Nisja më e fundit e riprodhimit.

Treg

Vendose nëse je platformë me dy anë.

Çelës	Lloji	Përshkrimi
`$seller_tier`	varg	Slug-u i nivelit në anën e shitësit.
`$buyer_tier`	varg	Slug-u i nivelit në anën e blerësit.
`$listings_count`	numër	Listime aktive në pronësi të përdoruesit.
`$reviews_count`	numër	Vlerësimet që ka marrë përdoruesi.
`$verified`	boolean	Statusi KYC.

Besnikëri

Vendose nëse ke programe angazhimi dhe shpërblimesh.

Çelës	Lloji	Përshkrimi
`$loyalty_points`	numër	Bilanci aktual i pikëve të përdorshme.
`$vip_level`	varg	Slug-u i nivelit VIP.
`$referral_count`	numër	Referime të suksesshme që i atribuohen këtij përdoruesi.

Këshillë

Nuk e sheh modelin tënd? Përdor çelësa të thjeshtë për traits custom. Ato shfaqen te paneli Custom Traits në dashboard, pa ndotur kolonat e profilit. 5 paketat vertikale më sipër janë sugjerime të arsyetuara për format më të zakonshme B2B — terminologjia specifike e klientit (p.sh. shipping_plan) mbetet pa prefiks.

Super-properties

Çifte çelës/vlerë për sesionin, që i bashkëngjiten automatikisht çdo eventi dalës. Ndryshe nga tiparet identify() (që përshkruajnë identitetin), super-properties përshkruajnë kontekstin e sesionit — varianti aktiv A/B, varianti i build-it, feature flags të aktivizuara me opt-in, affiliate ref. Ruhen në localStorage edhe pas ringarkimit; pastrohen në reset(). Në rast përplasjeje çelësash, properties për event në track() kanë gjithmonë përparësi.

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

Harta të nxehtësisë

Regjistrimi i hartës së nxehtësisë është aktiv si parazgjedhje — klikimet dhe thellësia e scroll-it, të dyja me kampionim 100 %. Lëvizja e mausit është opt-in (vëllim i lartë; aktivizoje për çdo faqe veçmas vetëm kur të duhet).

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

Riprodhim sesioni

Session replay regjistron një fotografi të DOM me rrweb dhe rrjedhën e ndryshimeve, që dashboard-i ta rindërtojë faqen si një sesion të navigueshëm krah gjurmës së eventeve. Bëhet fjalë për rindërtim të DOM, jo për regjistrim video të ekranit. Replay është i çaktivizuar si parazgjedhje. Aktivizoje për projektin te Paneli → Cilësimet → Riluajtja e sesionit; nuk kërkohet asnjë ndryshim në kodin e aplikacionit. Kur aktivizohet, regjistruesi shkarkohet nga një chunk i veçantë me version të përputhur.

Shënim

Burimi i së vërtetës është dashboard-i. Aty cakton Enable replay, Mask inputs, kohëzgjatjen maksimale dhe kontrollet e avancuara të kapjes. captureOnCellular ruhet në të njëjtën politikë projekti për iOS dhe Android; shfletuesit nuk ofrojnë një sinjal të besueshëm për Wi‑Fi kundrejt rrjetit celular, ndaj Web SDK e raporton dhe e injoron këtë kufizim që vlen vetëm për aplikacionet native.

Çfarë maskohet

Replay është projektuar që të mund të aktivizohet pa rrezik. Përmbajtjen sensitive e mbrojnë tri shtresa, të gjitha aktive si parazgjedhje:

Maskimi i të dhënave të futura kontrollohet nga projekti — kur cilësimi Masko fushat e hyrjes në Dashboard është aktiv (si parazgjedhje), karakteret e shtypura zëvendësohen me yje para se të dalin nga shfletuesi. Çaktivizoje vetëm për një nevojë të veçantë me ndjeshmëri të ulët; fushat e identitetit, autentikimit dhe pagesës mbeten të maskuara.
Atributi data-kixo-mask bllokon një element dhe gjithë nënstrukturën e tij. Vendose në çdo përmbajtës që mund të mbajë përmbajtje personale ose konfidenciale; replay përmban një placeholder, jo tekstin ose përmbajtjen DOM të asaj nënstrukture.
html
```
<div data-kixo-mask>
  
  
</div>
```
Fushat sensitive maskohen gjithmonë — fushat hyrëse që duken si fjalëkalim, numër karte, CVV, SSN, sekret ose token (nga type, name, id ose autocomplete) maskohen edhe kur cilësimi i projektit Masko fushat e hyrjes është i çaktivizuar. Edhe teksti i dukshëm dhe atributet e serializuara të DOM kalojnë nëpër pastruesin PII të Kixo para ngarkimit.

Mbledhja e të dhënave

SDK kap gjurmuesit e aktivizuar në integrim dhe në cilësimet e projektit, si edhe eventet dhe vetitë që dërgon aplikacioni yt.

Ku përfundojnë regjistrimet

SDK i kompreson me gzip eventet rrweb në segmente me madhësi të kufizuar, i kërkon Kixo një URL të nënshkruar për ngarkim të kufizuar për projektin dhe i ngarkon këto segmente drejtpërdrejt në ruajtjen e replay. Hape sesionin e rindërtuar te Replay → Sesionet; ai lidhet me gjurmën analitike të të njëjtit sesion.

Shënim

Replay varet nga plani yt. Sa sesione kapen dhe ruhen varet nga plani i projektit; në paketat më të ulëta, Kixo sërish regjistron metatëdhëna të lehta të sesionit, që sesioni të shfaqet në listat dhe analitikën tënde.

Flamujt e veçorive

Kontrollo vlerat e flag-eve në runtime me Kixo.getFeatureFlag().

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

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

Dërgimi dhe sjellja jashtë linje

SDK i ruan eventet lokalisht në radhë, i dërgon me paketa dhe riprovon dështimet e përkohshme me backoff. Nëse mbledhja pezullohet nga cilësimet e projektit, eventet e reja nuk dërgohen derisa mbledhja të riaktivizohet.

Diagnostikim

Pamje e gjendjes vetëm për lexim — e dobishme për diagnostikim në dev tools kur pyetja është "pse nuk po mbërrijnë eventet?"

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