Web SDK

Kixo Web SDK uz ugrađivanje u jednoj liniji automatski prati klikove, prikaze stranica, sesije, greške, dubinu skrolanja, web vitals, rage clickove, dead clickove i podatke za heatmapu. Praćenje mrežnih zahtjeva dostupno je kao opcionalna postavka. Distribuira se kao nativni ES modul i radi u modernim preglednicima.

Instalacija

Oznaka skripte (CDN)

Dodajte snippet prije zatvarajućeg taga </head>. Obratite pažnju na type="module" — obavezno je jer je SDK ES modul. Session replay je izdvojen u zaseban recorder chunk usklađen s verzijom, koji se učitava tek nakon uključivanja replaya, pa osnovni bundle ostaje mali 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 script URL-a i sam se inicijalizira. Ako opcije želite podešavati u kodu aplikacije, uklonite URL parametre i umjesto toga pozovite Kixo.init({...}) — globalni objekt Kixo dostupan je 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 kada opcije želite podešavati u kodu aplikacije, a ne kroz script URL. Izlaže isti Kixo API kao i CDN embed.

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 radite u AI builderu kao što su Lovable, Bolt, v0 ili Replit, zalijepite script-tag snippet direktno u chat buildera ili u postavke za ubacivanje koda. Većina buildera podržava dodavanje skripti u <head> vaše stranice.

Konfiguracija

Ugrađivanje u dvije linije koristi lokalne podrazumijevane analytics postavke ispod. Praćenje zahtjeva ostaje opcionalno. Session replay namjerno nije dio Kixo.init(): uključivanje, uzorkovanje, privatnost, trajanje i postavke snimanja dolaze isključivo iz projektnog dashboarda.

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 pod kontrolom projekta. Postavke na dashboardu mogu isključiti lokalne analytics trackere. Replay uopće nema lokalnu zastavicu za uključivanje: podesite ga pod Settings → Session replay, a SDK će pri sljedećem osvježavanju konfiguracije pratiti najnoviju politiku projekta.

Automatski praćeni događaji

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

page_view — svaka navigacija (početno učitavanje + SPA promjene ruta)
session_start / session_end
click — sve click interakcije 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ćeni JavaScript exceptioni + promise rejectioni
performance — metrike učitavanja stranice i Web Vitals (LCP, FCP, FID, CLS, INP, TTFB)
network_request — opcionalno trajanje zahtjeva kada je praćenje mreže uključeno
heatmap_click / scroll — podaci za heatmapu

Cijelu listu pogledajte u Referenca događaja.

Prilagođeni događaji

Kixo.track()

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

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

Tipizirani pomoćni eventi

Pojednostavljeni sloj preko Kixo.track() za događaje koje Kixo prepoznaje po nazivu (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Tipizirani wrapperi daju validaciju svojstava u vrijeme kompajliranja i jedinstven izvor istine za nazive ključeva — backend 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 trenutni uređaj s poznatim korisnikom. Rezervisani standardni ključevi svojstava nose prefiks $ (Mixpanel konvencija), pa su odvojeni od vaših prilagođenih traitova i prenose se u kolone profila na dashboardu — potpunu listu od 37 ključeva pogledajte pod Katalog standardnih svojstava.

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 trenutnom korisniku. Vrijednosti mogu biti stringovi, brojevi ili booleans — boolean oblik je najčistiji način da oznaka korisnika za kasnije ciljanje u segmentima, email 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 čuvaju u localStorage i nakon ponovnog učitavanja stranice te se automatski dodaju narednim događajima. Koristite ih u chatu s upitima poput "napravi email kampanju za korisnike gdje je subscribe true" — Kixo automatski sastavi segment i pripremi predložak. Brišu se na Kixo.reset().

Kixo.group()

Povežite korisnika s kompanijom ili organizacijom.

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

Kixo.reset()

Obrišite identitet, super-properties i trajno sačuvani queue. Pozovite ovo pri odjavi kako se naredni događaji ne bi pripisali prethodnom korisniku.

Kixo.reset();

Katalog standardnih svojstava

Rezervisani ključevi svojstava nose prefiks $, kako bi bili odvojeni od vaših prilagođenih svojstava. Kixo katalog pokriva 37 ključeva u 3 univerzalna paketa (identity, geo, lifecycle) i 5 B2B vertikalnih paketa (subscription, e-commerce, media, marketplace, loyalty). Postavite samo ono što se odnosi na vaš proizvod — dashboard se prilagođava i prikazuje samo pakete koje popunite.

Identitet

Uvijek relevantno. Postavlja kolone zaglavlja profila.

Ključ	Tip	Opis
`$email`	string	Primarni email, često ključ za spajanje identiteta.
`$phone`	string	E.164 broj telefona.
`$name`	string	Puno prikazano ime.
`$first_name`	string	Ime.
`$last_name`	string	Prezime.
`$avatar_url`	string	Puni URL slike avatara korisnika.

Geo

Geografski kontekst.

Ključ	Tip	Opis
`$country`	string	ISO 3166 kod države.
`$city`	string	Naziv grada.
`$region`	string	Savezna država ili pokrajina.
`$timezone`	string	IANA zona kao `America/Los_Angeles`.
`$language`	string	IETF oznaka kao `en` ili `ru-RU`.
`$locale`	string	Puni locale identifikator.

Životni ciklus

Kada smo ih vidjeli.

Ključ	Tip	Opis
`$created`	ISO8601	Vrijeme registracije ili kreiranja računa.
`$last_seen`	ISO8601	Vrijeme posljednje interakcije.

Pretplata

Postavite ako vaš proizvod ima pakete.

Ključ	Tip	Opis
`$plan`	string	Slug nivoa — `free`, `pro`, `enterprise`.
`$subscription_status`	string	`active` / `trial` / `cancelled` / `past_due`.
`$trial_ends`	ISO8601	Kada ističe trenutni probni period.
`$mrr`	broj	Mjesečni ponavljajući prihod u valuti računa.
`$subscription_started`	ISO8601	Kada je počela trenutna pretplata.

E-commerce

Postavite ako prodajete proizvode.

Ključ	Tip	Opis
`$lifetime_orders`	broj	Broj završenih narudžbi.
`$lifetime_revenue`	broj	Ukupna potrošnja.
`$aov`	broj	Prosječna vrijednost narudžbe.
`$last_purchase`	ISO8601	Posljednja uspješna kupovina.
`$first_purchase`	ISO8601	Prva uspješna kupovina.
`$cart_abandoned_count`	broj	Ukupan broj napuštenih korpi.

Mediji

Postavite ako objavljujete sadržaj.

Ključ	Tip	Opis
`$content_tier`	string	`free` / `premium` / `paid`.
`$subscribed_categories`	CSV string ili niz	Kategorije koje korisnik prati.
`$watch_time_total`	broj	Ukupno vrijeme gledanja u sekundama.
`$last_played`	ISO8601	Posljednji početak reprodukcije.

Tržište

Postavite ako ste dvosmjerna platforma.

Ključ	Tip	Opis
`$seller_tier`	string	Slug nivoa na strani prodavača.
`$buyer_tier`	string	Slug nivoa na strani kupca.
`$listings_count`	broj	Aktivni oglasi u vlasništvu korisnika.
`$reviews_count`	broj	Recenzije koje je korisnik primio.
`$verified`	boolean	KYC status.

Lojalnost

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

Ključ	Tip	Opis
`$loyalty_points`	broj	Trenutni raspoloživi saldo bodova.
`$vip_level`	string	VIP slug nivoa.
`$referral_count`	broj	Uspješne preporuke pripisane ovom korisniku.

Savjet

Ne vidite svoj obrazac? Za prilagođene traitove koristite obične ključeve. Pojavit će se u panelu Custom Traits na dashboardu bez zagađivanja kolona profila. Pet vertikalnih paketa iznad predstavljaju promišljene pretpostavke za najčešće B2B obrasce — terminologija specifična za kupca, npr. shipping_plan, ostaje bez prefiksa.

Super-properties

Ključ/vrijednost parovi na nivou sesije koji se automatski dodaju svakom odlaznom događaju. Za razliku od identify() svojstava, koja opisuju identitet, super-properties opisuju kontekst sesije — aktivnu A/B varijantu, build varijantu, uključene feature flagove i affiliate ref. Čuvaju se u localStorage i nakon ponovnog učitavanja stranice; brišu se na reset(). Kod sudara ključeva, 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();

Heatmape

Snimanje heatmape uključeno je po zadanim postavkama — klikovi i dubina skrolanja, oboje uzorkovani sa 100 %. Kretanje miša je opt-in (velik obim podataka; uključite ga po stranici ako vam treba).

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

Reprodukcija sesije

Session replay bilježi rrweb DOM snapshot i tok mutacija kako bi dashboard mogao rekonstruisati stranicu kao sesiju koju možete premotavati, zajedno s tragom događaja. Ovo je rekonstrukcija DOM-a, a ne videosnimak ekrana. Replay je podrazumijevano isključeno. Uključite ga za projekat u Kontrolna tabla → Postavke → Reprodukcija sesije; nisu potrebne promjene u kodu aplikacije. Kada ga uključite, snimač se preuzima iz zasebnog, verzijski usklađenog chunka.

Napomena

Dashboard je izvor istine. Tamo podesite Enable replay, Mask inputs, maksimalno trajanje i napredne kontrole snimanja. captureOnCellular se čuva u istoj politici projekta za iOS i Android; preglednici ne izlažu pouzdan signal za razlikovanje Wi‑Fi veze od mobilne mreže, pa Web SDK to ograničenje prijavi i zanemari jer važi samo za nativne aplikacije.

Šta se maskira

Replay je napravljen tako da ga možete sigurno uključiti. Osjetljiv sadržaj štite tri sloja, a svi su podrazumijevano uključeni:

Maskiranje unosa određuje projekat — dok je u Dashboardu uključena postavka Maskiraj unose (zadano), uneseni znakovi zamjenjuju se zvjezdicama prije nego što napuste preglednik. Isključite je samo za specifičnu potrebu niske osjetljivosti; polja za identitet, autentikaciju i plaćanje ostaju maskirana.
Atribut data-kixo-mask blokira element i cijelo njegovo podstablo. Postavite ga na svaki kontejner koji može sadržavati lične ili povjerljive podatke; replay će sadržavati placeholder, a ne tekst ili DOM sadržaj tog podstabla.
html
```
<div data-kixo-mask>
  
  
</div>
```
Osjetljiva polja su uvijek maskirana — inputi koji liče na lozinku, broj kartice, CVV, SSN, tajnu ili token (po tipu, nazivu, id-u ili autocompleteu) maskiraju se čak i kada 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 vašoj integraciji i postavkama projekta, kao i događaje i svojstva koje šalje aplikacija.

Gdje se snimci pohranjuju

SDK komprimira rrweb događaje pomoću gzipa u ograničene segmente, traži od Kixo projektno ograničen potpisani URL za upload i te segmente direktno šalje u replay storage. Rekonstruisanu sesiju otvorite pod Reprodukcija → Sesije; povezana je s analitičkim tragom iste sesije.

Napomena

Replay ovisi o vašem paketu. Koliko se sesija snima i zadržava zavisi od plana projekta; na nižim paketima Kixo i dalje bilježi lagane session metapodaci kako bi se sesija prikazala u listama i analitici.

Feature flagovi

Vrijednosti flagova u runtimeu provjerite preko Kixo.getFeatureFlag().

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

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

Isporuka i ponašanje van mreže

SDK lokalno reda događaje u queue, šalje ih u paketima i ponavlja privremene neuspjehe uz backoff. Ako je prikupljanje pauzirano u postavkama projekta, novi događaji se ne šalju dok se ponovo ne uključi.

Dijagnostika

Read-only pregled stanja — koristan za debugovanje u developerskim alatima kad treba odgovoriti na pitanje: "zašto mi događaji ne stižu?"

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