Web SDK

Το Kixo Web SDK καταγράφει αυτόματα κλικ, προβολές σελίδων, συνεδρίες, σφάλματα, βάθος κύλισης, web vitals, rage-clicks, dead-clicks και δεδομένα heatmap με μία μόνο γραμμή ενσωμάτωσης. Η παρακολούθηση αιτημάτων δικτύου διατίθεται ως προαιρετική ρύθμιση. Διανέμεται ως native ES module και λειτουργεί σε σύγχρονους browsers.

Εγκατάσταση

Ετικέτα script (CDN)

Προσθέστε το snippet πριν από το κλείσιμο του tag </head>. Προσέξτε το type="module" — απαιτείται επειδή το SDK είναι ES module. Το session replay είναι χωρισμένο σε 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({...}) — το global αντικείμενο Kixo είναι διαθέσιμο μόλις φορτωθεί το module.

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. Παρέχει το ίδιο API Kixo με την ενσωμάτωση μέσω CDN.

bash

npm install @kixo.io/web

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

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

Πλατφόρμες χωρίς κώδικα

Αν φτιάχνετε με builder που χρησιμοποιεί AI, όπως τα Lovable, Bolt, v0 ή Replit, επικολλήστε το snippet του script tag απευθείας στο chat του builder ή στις ρυθμίσεις εισαγωγής κώδικα. Οι περισσότεροι builders υποστηρίζουν προσθήκη scripts στο <head> του site σας.

Ρύθμιση

Η ενσωμάτωση δύο γραμμών χρησιμοποιεί τις τοπικές προεπιλογές analytics που ακολουθούν. Η παρακολούθηση αιτημάτων παραμένει προαιρετική. Το session replay λείπει σκόπιμα από το Kixo.init(): η ενεργοποίηση, η δειγματοληψία, οι ρυθμίσεις απορρήτου, η διάρκεια και οι ρυθμίσεις καταγραφής ορίζονται μόνο από το dashboard του project.

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

});

Σημείωση

Οι ρυθμίσεις Ρύθμιση που ελέγχεται από το project. στο Dashboard μπορούν να απενεργοποιήσουν τοπικούς analytics trackers. Το Replay δεν έχει καθόλου τοπικό θετικό enable flag: ρυθμίστε το στο Settings → Session replay και το SDK θα ακολουθήσει την πιο πρόσφατη πολιτική του project στην επόμενη ανανέωση ρυθμίσεων.

Συμβάντα αυτόματης καταγραφής

Με την προεπιλεγμένη ρύθμιση, το Kixo καταγράφει αυτόματα τα παρακάτω events χωρίς επιπλέον κώδικα:

page_view — κάθε πλοήγηση (αρχική φόρτωση + αλλαγές διαδρομής SPA)
session_start / session_end
click — όλες οι αλληλεπιδράσεις κλικ με selector στοιχείου
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 — δεδομένα heatmap

Δείτε την πλήρη λίστα στο Αναφορά συμβάντων.

Προσαρμοσμένα συμβάντα

Kixo.track()

Στείλτε ένα προσαρμοσμένο event με προαιρετικές ιδιότητες.

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

Τυποποιημένα βοηθήματα για events

Συντακτική διευκόλυνση πάνω από το Kixo.track() για τα events που το Kixo αναγνωρίζει ονομαστικά (purchase, signup, subscribe_start,trial_start, cancel, upgrade,activation, share, invite). Τα typed wrappers προσφέρουν έλεγχο ιδιοτήτων κατά τη μεταγλώττιση και ενιαίο σημείο αναφοράς για τα ονόματα κλειδιών — ο ανιχνευτής standard events του 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()

Συσχετίστε την τρέχουσα συσκευή με γνωστό χρήστη. Τα δεσμευμένα standard property keys έχουν πρόθεμα $ (σύμβαση Mixpanel), ώστε να ξεχωρίζουν από τα δικά σας custom traits και να προωθούνται στις στήλες προφίλ του dashboard — δείτε το Τυπικός κατάλογος ιδιοτήτων παρακάτω για την πλήρη λίστα με τα 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() — προσθήκη ετικέτας σε χρήστη για τμηματοποίηση

Προσθέστε αυθαίρετα attributes key/value στον τρέχοντα χρήστη. Οι τιμές μπορούν να είναι strings, numbers ή booleans — η μορφή boolean είναι ο καθαρότερος τρόπος να επισημάνετε έναν χρήστη με ετικέτα για μελλοντική στόχευση σε segments, καμπάνιες email ή ερωτήματα 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' });

Οι ιδιότητες αποθηκεύονται στο localStorage, διατηρούνται μετά από reload και προστίθενται αυτόματα στα επόμενα events. Χρησιμοποιήστε τες στο chat με prompts όπως "δημιούργησε μια καμπάνια email για χρήστες όπου το subscribe είναι true" — το Kixo δημιουργεί αυτόματα το segment και ετοιμάζει το template. Καθαρίζονται με το Kixo.reset().

Kixo.group()

Συσχετίστε τον χρήστη με εταιρεία ή οργανισμό.

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

Kixo.reset()

Καθαρίστε την ταυτότητα, τα super-properties και την αποθηκευμένη ουρά. Καλέστε το στο logout ώστε τα επόμενα events να μην αποδοθούν στον προηγούμενο χρήστη.

Kixo.reset();

Τυπικός κατάλογος ιδιοτήτων

Τα δεσμευμένα κλειδιά ιδιοτήτων έχουν πρόθεμα $, ώστε να ξεχωρίζουν από τα δικά σας custom traits. Ο κατάλογος του Kixo καλύπτει 37 κλειδιά σε 3 οριζόντια πακέτα (identity, geo, lifecycle) και 5 κάθετα πακέτα για B2B (subscription, e-commerce, media, marketplace, loyalty). Ορίστε όσα ταιριάζουν στο προϊόν σας — το dashboard προσαρμόζεται και εμφανίζει μόνο τα πακέτα που έχετε συμπληρώσει.

Ταυτότητα

Πάντα σχετικό. Ορίζει τις στήλες στην κεφαλίδα του προφίλ.

Κλειδί	Τύπος	Περιγραφή
`$email`	συμβολοσειρά	Κύριο email, συχνά ως κλειδί συγχώνευσης για τη σύνδεση ταυτοτήτων.
`$phone`	συμβολοσειρά	Αριθμός τηλεφώνου σε μορφή E.164.
`$name`	συμβολοσειρά	Πλήρες εμφανιζόμενο όνομα.
`$first_name`	συμβολοσειρά	Όνομα.
`$last_name`	συμβολοσειρά	Επώνυμο.
`$avatar_url`	συμβολοσειρά	Πλήρες URL της εικόνας avatar του χρήστη.

Γεωγραφικά στοιχεία

Γεωγραφικό πλαίσιο.

Κλειδί	Τύπος	Περιγραφή
`$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	Τελευταία έναρξη αναπαραγωγής.

Marketplace

Ορίστε το αν το προϊόν σας είναι πλατφόρμα δύο πλευρών.

Κλειδί	Τύπος	Περιγραφή
`$seller_tier`	συμβολοσειρά	Slug βαθμίδας για την πλευρά του πωλητή.
`$buyer_tier`	συμβολοσειρά	Slug βαθμίδας από την πλευρά του αγοραστή.
`$listings_count`	αριθμός	Ενεργές καταχωρίσεις του χρήστη.
`$reviews_count`	αριθμός	Αξιολογήσεις που έχει λάβει ο χρήστης.
`$verified`	boolean	Κατάσταση KYC.

Πιστότητα

Ορίστε το αν έχετε προγράμματα αφοσίωσης και επιβράβευσης.

Κλειδί	Τύπος	Περιγραφή
`$loyalty_points`	αριθμός	Τρέχον διαθέσιμο υπόλοιπο πόντων.
`$vip_level`	συμβολοσειρά	Slug βαθμίδας VIP.
`$referral_count`	αριθμός	Επιτυχημένες παραπομπές που αποδίδονται σε αυτόν τον χρήστη.

Συμβουλή

Δεν βλέπετε το μοτίβο σας; Χρησιμοποιήστε σκέτα keys για custom traits. Εμφανίζονται στο panel Custom Traits του dashboard χωρίς να γεμίζουν τις στήλες προφίλ. Τα 5 vertical packs παραπάνω είναι σκόπιμες επιλογές για τα πιο συνηθισμένα σχήματα B2B — ορολογία ειδική για κάθε πελάτη (π.χ. shipping_plan) μένει χωρίς πρόθεμα.

Super-properties

Ζεύγη κλειδιού/τιμής ανά session που προστίθενται αυτόματα σε κάθε εξερχόμενο event. Διαφέρουν από τα traits του identify() (που περιγράφουν την ταυτότητα)· τα super-properties περιγράφουν το πλαίσιο του session — ενεργή παραλλαγή A/B, τύπος build, ενεργά feature flags, affiliate ref. Αποθηκεύονται στο localStorage και διατηρούνται μετά από reload· καθαρίζονται με το reset(). Σε σύγκρουση κλειδιών, τα ανά-event 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();

Heatmaps

Η καταγραφή heatmap είναι ενεργή από προεπιλογή — κλικ και βάθος κύλισης, και τα δύο με δειγματοληψία 100 %. Η κίνηση του ποντικιού είναι προαιρετική (μεγάλος όγκος· ενεργοποιήστε τη ανά σελίδα αν είναι χρήσιμη).

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

Αναπαραγωγή συνεδρίας

Το session replay καταγράφει ένα στιγμιότυπο DOM του rrweb και τη ροή μεταβολών, ώστε το dashboard να μπορεί να ανασυνθέσει τη σελίδα ως συνεδρία με δυνατότητα περιήγησης δίπλα στη ροή των event. Πρόκειται για ανασύνθεση DOM και όχι για εγγραφή βίντεο οθόνης. Το replay είναι απενεργοποιημένο από προεπιλογή. Ενεργοποιήστε το για το project από το Πίνακας ελέγχου → Ρυθμίσεις → Αναπαραγωγή συνεδρίας· δεν απαιτείται καμία αλλαγή στον κώδικα της εφαρμογής. Όταν ενεργοποιηθεί, ο recorder φορτώνεται από ξεχωριστό chunk με αντίστοιχη έκδοση.

Σημείωση

Το dashboard είναι η πηγή αλήθειας. Εκεί ορίζετε τα Enable replay, Mask inputs, τη μέγιστη διάρκεια και τα σύνθετα στοιχεία ελέγχου καταγραφής. Το captureOnCellular αποθηκεύεται στην ίδια πολιτική project για iOS και Android· οι browsers δεν εκθέτουν αξιόπιστο σήμα για διάκριση Wi‑Fi από δίκτυο κινητής, οπότε το Web SDK το αναφέρει και αγνοεί αυτόν τον περιορισμό που ισχύει μόνο σε native.

Τι αποκρύπτεται

Το Replay είναι σχεδιασμένο ώστε να ενεργοποιείται με ασφάλεια. Τρία επίπεδα προστατεύουν το ευαίσθητο περιεχόμενο και είναι όλα ενεργά από προεπιλογή:

Η απόκρυψη στα πεδία εισαγωγής ελέγχεται από το project — όταν η ρύθμιση Απόκρυψη πεδίων εισαγωγής στο Dashboard είναι ενεργή (προεπιλογή), οι χαρακτήρες που πληκτρολογούνται αντικαθίστανται με αστερίσκους πριν φύγουν από τον browser. Απενεργοποιήστε τη μόνο για συγκεκριμένη ανάγκη χαμηλής ευαισθησίας· τα πεδία ταυτότητας, πιστοποίησης και πληρωμών παραμένουν καλυμμένα.
Το Το attribute data-kixo-mask αποκλείει ένα στοιχείο και ολόκληρο το υποδένδρο του. Τοποθετήστε το σε οποιοδήποτε container μπορεί να περιέχει προσωπικό ή εμπιστευτικό περιεχόμενο· το replay θα περιέχει placeholder, όχι το κείμενο ή το περιεχόμενο DOM αυτού του υποδένδρου.
html
```
<div data-kixo-mask>
  
  
</div>
```
Τα ευαίσθητα πεδία αποκρύπτονται πάντα — πεδία εισαγωγής που μοιάζουν με κωδικό πρόσβασης, αριθμό κάρτας, CVV, SSN, secret ή token (από το type, name, id ή autocomplete) καλύπτονται ακόμη και όταν η ρύθμιση Απόκρυψη πεδίων εισαγωγής του project είναι απενεργοποιημένη. Το ορατό κείμενο και τα σειριοποιημένα attributes του DOM περνούν επίσης από το φίλτρο PII του Kixo πριν από την αποστολή.

Συλλογή δεδομένων

Το SDK καταγράφει τους trackers που είναι ενεργοί στην ενσωμάτωση και στις ρυθμίσεις του project σας, καθώς και τα events και τις ιδιότητες που στέλνει η εφαρμογή σας.

Πού αποθηκεύονται οι εγγραφές

Το SDK συμπιέζει τα rrweb events με gzip σε τμηματοποιημένα κομμάτια περιορισμένου μεγέθους, ζητά από το Kixo ένα υπογεγραμμένο URL μεταφόρτωσης με εμβέλεια project και ανεβάζει αυτά τα κομμάτια απευθείας στον χώρο αποθήκευσης του replay. Ανοίξτε την ανασυντεθειμένη συνεδρία από το Αναπαραγωγή → Συνεδρίες· συνδέεται με τη ροή analytics της ίδιας συνεδρίας.

Σημείωση

Το Replay εξαρτάται από το πλάνο σας. Ο αριθμός των sessions που καταγράφονται και διατηρούνται εξαρτάται από το πλάνο του project σας· στα χαμηλότερα tiers το Kixo εξακολουθεί να καταγράφει ελαφριά session μεταδεδομένα, ώστε το session να εμφανίζεται στις λίστες και στα analytics σας.

Σημαίες λειτουργιών

Ελέγξτε τις τιμές των flags κατά τον χρόνο εκτέλεσης μέσω του Kixo.getFeatureFlag().

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

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

Παράδοση και συμπεριφορά εκτός σύνδεσης

Το SDK βάζει τα events σε τοπική ουρά, τα στέλνει σε παρτίδες και επαναλαμβάνει τις προσωρινές αποτυχίες με backoff. Αν η συλλογή παγώσει από τις ρυθμίσεις του project, τα νέα events δεν αποστέλλονται μέχρι να ενεργοποιηθεί ξανά.

Διαγνωστικά

Στιγμιότυπο κατάστασης μόνο για ανάγνωση — χρήσιμο για debugging τύπου «γιατί δεν φτάνουν τα events μου;» στα dev tools.

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