Web SDK

Kixo Web SDK jednim retkom za ugradnju automatski prati klikove, prikaze stranica, sesije, pogreške, dubinu skrolanja, web vitalne metrike, rage clickove, dead clickove i podatke za toplinske karte. Praćenje mrežnih zahtjeva dostupno je kao opcionalna postavka. Isporučuje se kao izvorni ES modul i radi u modernim preglednicima.

Instalacija

Script oznaka (CDN)

Dodajte isječak prije završne oznake </head>. Obratite pozornost na type="module" — obavezno je jer je SDK ES modul. Session replay odvojen je u recorder chunk usklađen s verzijom, koji se učitava tek nakon uključivanja replaya, pa osnovni bundle ostaje malen dok je replay isključen.

html

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

Napomena

SDK čita project_id i api_key iz URL-a skripte i sam se inicijalizira. Ako opcije želite postavljati u kodu aplikacije, uklonite parametre iz URL-a i umjesto toga pozovite Kixo.init({...}) — globalni objekt Kixo bit će dostupan nakon učitavanja modula.

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

Koristite ovo kad opcije želite postavljati u kodu aplikacije, a ne preko URL-a skripte. Izlaže isti Kixo API kao i ugradnja preko CDN-a.

bash

npm install @kixo.io/web

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

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

No-code platforme

Ako gradite uz pomoć AI buildera kao što su Lovable, Bolt, v0 ili Replit, zalijepite script-tag isječak izravno u chat svojeg buildera ili u postavke za ubacivanje koda. Većina buildera podržava dodavanje skripti u <head> vaše stranice.

Konfiguracija

Ugradnja u dva retka koristi lokalne zadane postavke analitike navedene niže. Praćenje zahtjeva i dalje se uključuje zasebno. Session replay namjerno nije dio Kixo.init(): uključivanje, uzorkovanje, privatnost, trajanje i postavke snimanja dolaze isključivo iz nadzorne ploče projekta.

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

});

Napomena

Konfiguracija kojom upravlja projekt. Postavke u Dashboardu mogu isključiti lokalne analytics trackere. Replay uopće nema lokalnu oznaku za uključivanje: konfigurira se pod Settings → Session replay, a SDK pri sljedećem osvježavanju konfiguracije primjenjuje najnoviju projektnu politiku.

Automatski praćeni događaji

Uz zadanu konfiguraciju Kixo automatski bilježi ove događaje bez dodatnog koda:

page_view — svaka navigacija (početno učitavanje + promjene ruta u SPA aplikaciji)
session_start / session_end
click — sve interakcije klika sa selektorom elementa
scroll_depth — pragovi 25 / 50 / 75 / 100 %
rage_click — ponovljeni klikovi na isti element
dead_click — klikovi na neinteraktivne elemente
error — neuhvaćene JavaScript iznimke + odbijanja promisea
performance — metrike učitavanja stranice i Web Vitals (LCP, FCP, FID, CLS, INP, TTFB)
network_request — neobavezno mjerenje trajanja zahtjeva kada je uključeno praćenje mreže
heatmap_click / scroll — podaci za toplinsku kartu

Cijeli popis pogledajte u Referenca događaja.

Prilagođeni događaji

Kixo.track()

Pošaljite prilagođeni događaj s neobaveznim svojstvima.

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

Tipizirani pomoćnici za događaje

Praktični sloj nad Kixo.track() za događaje koje Kixo prepoznaje po nazivu (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Tipizirani omotači donose provjeru svojstava pri kompilaciji i jedan izvor istine za nazive ključeva — backendov detektor standardnih događaja traži potpuno podudaranje.

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

Povežite trenutačni uređaj s poznatim korisnikom. Rezervirani standardni ključevi svojstava imaju prefiks $ (Mixpanel konvencija), pa su odvojeni od vaših prilagođenih atributa i prikazuju se u stupcima profila na dashboardu — potpuni popis svih 37 ključeva nalazi se u Katalog standardnih svojstava niže.

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() — označite korisnika za segmentaciju

Dodajte proizvoljne atribute ključ/vrijednost trenutačnom korisniku. Vrijednosti mogu biti stringovi, brojevi ili boolean vrijednosti — boolean je najčišći način da oznaka korisnika za kasnije ciljanje u segmentima, e-mail kampanjama ili chat upitima.

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

Svojstva se spremaju u localStorage, ostaju nakon ponovnog učitavanja i automatski se dodaju sljedećim događajima. U chatu ih možete koristiti upitima poput "izradi e-mail kampanju za korisnike kod kojih je subscribe true" — Kixo automatski sastavlja segment i priprema predložak. Brišu se pri Kixo.reset().

Kixo.group()

Povežite korisnika s tvrtkom ili organizacijom.

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

Kixo.reset()

Očistite identitet, super-svojstva i trajno spremljeni red. Pozovite ovo pri odjavi kako se sljedeći događaji ne bi pripisali prethodnom korisniku.

Kixo.reset();

Katalog standardnih svojstava

Rezervirani ključevi svojstava nose prefiks $ kako bi bili odvojeni od vaših prilagođenih atributa. Kixo katalog pokriva 37 ključeva u 3 univerzalna paketa (identitet, geo, životni ciklus) i 5 B2B vertikalnih paketa (pretplata, e-trgovina, mediji, marketplace, program vjernosti). Postavite samo ono što odgovara vašem proizvodu — nadzorna ploča prilagođava se i prikazuje samo pakete koje popunite.

Identitet

Uvijek relevantno. Postavlja stupce zaglavlja profila.

Ključ	Vrsta	Opis
`$email`	tekst	Primarna adresa e-pošte, često glavni ključ za spajanje identiteta.
`$phone`	tekst	Telefonski broj u formatu E.164.
`$name`	tekst	Puni prikazni naziv.
`$first_name`	tekst	Ime.
`$last_name`	tekst	Prezime.
`$avatar_url`	tekst	Puni URL korisnikove avatar slike.

Geo

Geografski kontekst.

Ključ	Vrsta	Opis
`$country`	tekst	ISO 3166 kod države.
`$city`	tekst	Naziv grada.
`$region`	tekst	Država, savezna država ili pokrajina.
`$timezone`	tekst	IANA zona poput `America/Los_Angeles`.
`$language`	tekst	IETF oznaka poput `en` ili `ru-RU`.
`$locale`	tekst	Puni identifikator lokalizacije.

Životni ciklus

Kad smo ih vidjeli.

Ključ	Vrsta	Opis
`$created`	ISO8601	Vrijeme registracije ili otvaranja računa.
`$last_seen`	ISO8601	Vrijeme zadnje interakcije.

Pretplata

Postavite ako vaš proizvod ima pakete.

Ključ	Vrsta	Opis
`$plan`	tekst	Slug razine — `free`, `pro`, `enterprise`.
`$subscription_status`	tekst	`active` / `trial` / `cancelled` / `past_due`.
`$trial_ends`	ISO8601	Kad istječe trenutačno probno razdoblje.
`$mrr`	broj	Mjesečni ponavljajući prihod u valuti računa.
`$subscription_started`	ISO8601	Kad je počela trenutačna pretplata.

E-trgovina

Postavite ako prodajete proizvode.

Ključ	Vrsta	Opis
`$lifetime_orders`	broj	Broj dovršenih narudžbi.
`$lifetime_revenue`	broj	Ukupna potrošnja.
`$aov`	broj	Prosječna vrijednost narudžbe.
`$last_purchase`	ISO8601	Vrijeme zadnje uspješne kupnje.
`$first_purchase`	ISO8601	Prva uspješna kupnja.
`$cart_abandoned_count`	broj	Ukupan broj napuštanja košarice.

Mediji

Postavite ako objavljujete sadržaj.

Ključ	Vrsta	Opis
`$content_tier`	tekst	`free` / `premium` / `paid`.
`$subscribed_categories`	CSV string ili polje	Kategorije koje korisnik prati.
`$watch_time_total`	broj	Ukupno vrijeme gledanja u sekundama.
`$last_played`	ISO8601	Vrijeme zadnjeg pokretanja reprodukcije.

Marketplace

Postavite ako ste dvostrana platforma.

Ključ	Vrsta	Opis
`$seller_tier`	tekst	Slug paketa na strani prodavatelja.
`$buyer_tier`	tekst	Slug paketa na strani kupca.
`$listings_count`	broj	Aktivni oglasi koje korisnik posjeduje.
`$reviews_count`	broj	Recenzije koje je korisnik primio.
`$verified`	boolean	KYC status.

Program vjernosti

Postavite ako imate programe angažmana i nagrađivanja.

Ključ	Vrsta	Opis
`$loyalty_points`	broj	Trenutačno stanje iskoristivih bodova.
`$vip_level`	tekst	Slug VIP razine.
`$referral_count`	broj	Uspješne preporuke pripisane ovom korisniku.

Savjet

Ne vidite svoj obrazac? Za prilagođene atribute koristite obične ključeve. Prikazat će se u panelu Custom Traits na dashboardu, bez zatrpavanja stupaca profila. Pet vertikalnih paketa iznad promišljene su pretpostavke najčešćih B2B obrazaca — terminologija specifična za vaš proizvod (npr. shipping_plan) ostaje bez prefiksa.

Super-svojstva

Parovi ključ/vrijednost na razini sesije koji se automatski dodaju svakom odlaznom događaju. Za razliku od atributa identify(), koji opisuju identitet, super-svojstva opisuju kontekst sesije — aktivnu A/B varijantu, varijantu builda, uključene feature flagove i affiliate referencu. Spremaju se u localStorage i ostaju nakon ponovnog učitavanja; brišu se pri reset(). Ako dođe do sudara ključeva, svojstva po događaju properties na track() uvijek imaju prednost.

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

Toplinske karte

Snimanje toplinskih karata uključeno je prema zadanim postavkama — klikovi i dubina skrolanja, oboje uzorkovani sa 100 %. Kretanje miša uključuje se zasebno (velik volumen podataka; uključite ga po stranici ako vam je korisno).

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

Snimka sesije

Session replay bilježi rrweb snimku DOM-a i tok promjena kako bi nadzorna ploča mogla rekonstruirati stranicu kao sesiju kroz koju se može pomicati, usporedno s tragom događaja. To je rekonstrukcija DOM-a, a ne videosnimka zaslona. Replay je zadano isključeno. Uključite ga za projekt u Nadzorna ploča → Postavke → Reprodukcija sesije; nije potrebna nikakva promjena koda aplikacije. Kad se uključi, snimač se dohvaća iz zasebnog chunka usklađenog s verzijom.

Napomena

Nadzorna ploča je izvor istine. Ondje postavite Enable replay, Mask inputs, maksimalno trajanje i napredne kontrole snimanja. captureOnCellular se sprema u istu projektnu politiku za iOS i Android; preglednici ne izlažu pouzdan signal za razlikovanje Wi‑Fi veze od mobilne mreže, pa Web SDK prijavi i zanemari to ograničenje koje vrijedi samo za nativne aplikacije.

Što se maskira

Replay je osmišljen tako da ga možete sigurno uključiti. Osjetljivi sadržaj štite tri sloja, svi uključeni prema zadanim postavkama:

Maskiranje unosa određuje projekt — dok je postavka Maskiraj unose na Dashboardu uključena (zadano), upisani znakovi zamjenjuju se zvjezdicama prije nego što napuste preglednik. Isključite je samo za točno određenu potrebu niske osjetljivosti; polja za identitet, autentikaciju i plaćanje i dalje ostaju maskirana.
Atribut data-kixo-mask blokira element i cijelo njegovo podstablo. Postavite ga na svaki spremnik koji može sadržavati osobne ili povjerljive podatke; u replayu će se prikazati zamjena, a ne tekst ili DOM sadržaj tog podstabla.
html
```
<div data-kixo-mask>
  
  
</div>
```
Osjetljiva polja uvijek se maskiraju — unosi koji izgledaju kao lozinka, broj kartice, CVV, SSN, tajna ili token (prema type, name, id ili autocomplete) maskiraju se čak i kad je postavka projekta Maskiraj unose isključena. Vidljivi tekst i serijalizirani DOM atributi također prolaze kroz Kixo PII sanitizer prije slanja.

Prikupljanje podataka

SDK bilježi trackere uključene u integraciji i postavkama projekta, kao i događaje i svojstva koje šalje vaša aplikacija.

Gdje završavaju snimke

SDK komprimira rrweb događaje u gzip, slaže ih u ograničene segmente, traži od Kixo projektno ograničen potpisani URL za prijenos i te segmente izravno šalje u pohranu za replay. Rekonstruiranu sesiju otvorite u Reprodukcija → Sesije; povezana je s analitičkim tragom iste sesije.

Napomena

Replay ovisi o vašem paketu. Koliko se sesija snima i čuva ovisi o vašem projektnom planu; na nižim paketima Kixo i dalje bilježi lagane metapodatke sesije metapodaci kako bi se sesija prikazivala u popisima i analitici.

Feature flagovi

Vrijednosti flagova provjerite tijekom izvođenja putem Kixo.getFeatureFlag().

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

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

Isporuka i ponašanje izvan mreže

SDK lokalno stavlja događaje u red, šalje ih u paketima i kod prolaznih grešaka pokušava ponovno uz backoff. Ako je prikupljanje pauzirano u postavkama projekta, novi se događaji neće slati dok se ponovno ne uključi.

Dijagnostika

Pregled stanja samo za čitanje — koristan za otkrivanje problema tipa "zašto mi događaji ne prolaze?" u razvojnim alatima.

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