SDK Web

Le SDK Web Kixo suit automatiquement les clics, les vues de page, les sessions, les erreurs, la profondeur de défilement, les Web Vitals, les rage clicks, les dead clicks et les données de carte de chaleur avec une intégration en une ligne. Le suivi des requêtes réseau est disponible en option. Distribué sous forme de module ES natif, il fonctionne dans les navigateurs modernes.

Installation

Balise script (CDN)

Ajoutez l’extrait avant la balise fermante </head>. Notez le type="module" : il est obligatoire, car le SDK est un module ES. La relecture de session est séparée dans un chunk d’enregistrement aligné sur la version, chargé uniquement après l’activation de la relecture ; le bundle de base reste donc léger tant que la relecture est désactivée.

html

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

Remarque

Le SDK lit project_id et api_key dans l’URL du script, puis s’initialise. Pour configurer les options dans le code applicatif, retirez les paramètres de l’URL et appelez plutôt Kixo.init({...}) ; l’objet global Kixo est disponible une fois le module chargé.

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

À utiliser si vous préférez configurer les options dans le code applicatif plutôt que via l’URL du script. Cette intégration expose la même API Kixo que l’intégration CDN.

bash

npm install @kixo.io/web

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

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

Plateformes no-code

Si vous créez avec un builder propulsé par AI comme Lovable, Bolt, v0 ou Replit, collez l’extrait avec balise script directement dans le chat de l’outil ou dans ses réglages d’injection de code. La plupart de ces builders permettent d’ajouter des scripts dans le <head> de votre site.

Configuration

L’intégration en deux lignes utilise les valeurs analytiques locales par défaut ci-dessous. Le suivi des requêtes reste facultatif. Le replay de session est volontairement absent de Kixo.init() : son activation, son échantillonnage, ses paramètres de confidentialité, sa durée et ses paramètres de capture proviennent uniquement du dashboard du projet.

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

});

Remarque

Les paramètres Configuration définie au niveau du projet. du Dashboard peuvent désactiver les traceurs d’analyse locaux. La relecture, elle, n’a aucun indicateur local d’activation : configurez-la dans Settings → Session replay, et le SDK appliquera la dernière politique du projet lors du prochain rafraîchissement de configuration.

Événements suivis automatiquement

Avec la configuration par défaut, Kixo collecte automatiquement les événements suivants, sans code supplémentaire :

page_view — chaque navigation (chargement initial + changements de route SPA)
session_start / session_end
click — tous les clics sur les éléments correspondant au sélecteur
scroll_depth — seuils à 25 / 50 / 75 / 100 %
rage_click — clics répétés sur le même élément
dead_click — clics sur des éléments non interactifs
error — exceptions JavaScript non interceptées + rejets de promesses
performance — métriques de chargement de page et Web Vitals (LCP, FCP, FID, CLS, INP, TTFB)
network_request — chronométrage des requêtes, si le suivi réseau est activé
heatmap_click / scroll — données de carte thermique

Consultez la liste complète dans Référence des événements.

Événements personnalisés

Kixo.track()

Envoyer un événement personnalisé avec des propriétés facultatives.

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

Helpers d’événements typés

Surcouche de Kixo.track() pour les événements que Kixo reconnaît par leur nom (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Ces helpers typés apportent une validation des propriétés à la compilation et une source unique pour les noms de clés ; le détecteur d’événements standard du backend fait une correspondance exacte.

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

Associez l’appareil actuel à un utilisateur connu. Les clés de propriété standard réservées portent le préfixe $ (convention Mixpanel), ce qui les distingue de vos propres attributs personnalisés et les fait remonter dans les colonnes de profil du dashboard — voir le Catalogue des propriétés standard ci-dessous pour la liste complète des 37 clés.

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() — marquer un utilisateur pour la segmentation

Ajoutez à l’utilisateur actuel des attributs clé/valeur arbitraires. Les valeurs peuvent être des chaînes, des nombres ou des booléens — la forme booléenne est le moyen le plus simple de étiquette un utilisateur pour le cibler ensuite dans des segments, des campagnes e-mail ou des requêtes de 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' });

Les propriétés sont conservées dans localStorage entre les rechargements et ajoutées automatiquement aux événements suivants. Vous pouvez les utiliser dans le chat avec des prompts comme "créer une campagne e-mail pour les utilisateurs dont subscribe vaut true" : Kixo crée alors automatiquement un segment et prépare le modèle. Elles sont effacées lors de Kixo.reset().

Kixo.group()

Associez l’utilisateur à une entreprise ou à une organisation.

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

Kixo.reset()

Efface l’identité, les super-propriétés et la file persistée. Appelez cette méthode à la déconnexion pour éviter que les événements suivants soient attribués à l’utilisateur précédent.

Kixo.reset();

Catalogue des propriétés standard

Les clés de propriété réservées portent le préfixe $, ce qui les isole de vos attributs personnalisés. Le catalogue de Kixo couvre 37 clés réparties en 3 packs universels (identité, géolocalisation, cycle de vie) et 5 packs métier B2B (abonnement, e-commerce, médias, marketplace, fidélité). Définissez uniquement celles qui s’appliquent à votre produit : le dashboard s’adapte et n’affiche que les packs que vous renseignez.

Identité

Toujours pertinent. Définit les colonnes d’en-tête du profil.

Clé	Type	Description
`$email`	chaîne de caractères	Adresse e-mail principale, souvent utilisée comme clé de rapprochement d’identité.
`$phone`	chaîne de caractères	Numéro de téléphone au format E.164.
`$name`	chaîne de caractères	Nom d’affichage complet.
`$first_name`	chaîne de caractères	Prénom.
`$last_name`	chaîne de caractères	Nom de famille.
`$avatar_url`	chaîne de caractères	URL complète de l’image d’avatar de l’utilisateur.

Géographie

Contexte géographique.

Clé	Type	Description
`$country`	chaîne de caractères	Code pays ISO 3166.
`$city`	chaîne de caractères	Nom de la ville.
`$region`	chaîne de caractères	État ou province.
`$timezone`	chaîne de caractères	Zone IANA telle que `America/Los_Angeles`.
`$language`	chaîne de caractères	Tag IETF tel que `en` ou `ru-RU`.
`$locale`	chaîne de caractères	Identifiant de langue complet.

Cycle de vie

À quel moment les avons-nous vus ?

Clé	Type	Description
`$created`	ISO8601	Date d’inscription ou de création du compte.
`$last_seen`	ISO8601	Date du dernier engagement.

Abonnement

À renseigner si votre produit propose des offres.

Clé	Type	Description
`$plan`	chaîne de caractères	Slug du palier — `free`, `pro`, `enterprise`.
`$subscription_status`	chaîne de caractères	`active` / `trial` / `cancelled` / `past_due`.
`$trial_ends`	ISO8601	Date d’expiration de l’essai en cours.
`$mrr`	nombre	Revenu mensuel récurrent dans la devise du compte.
`$subscription_started`	ISO8601	Date de début de l’abonnement en cours.

E-commerce

À renseigner si vous vendez des produits.

Clé	Type	Description
`$lifetime_orders`	nombre	Nombre de commandes finalisées.
`$lifetime_revenue`	nombre	Dépenses totales.
`$aov`	nombre	Valeur moyenne des commandes.
`$last_purchase`	ISO8601	Dernier achat réussi.
`$first_purchase`	ISO8601	Premier achat réussi.
`$cart_abandoned_count`	nombre	Nombre total d’abandons de panier.

Médias

À renseigner si vous publiez du contenu.

Clé	Type	Description
`$content_tier`	chaîne de caractères	`free` / `premium` / `paid`.
`$subscribed_categories`	Chaîne CSV ou tableau	Catégories suivies par l’utilisateur.
`$watch_time_total`	nombre	Temps de visionnage cumulé en secondes.
`$last_played`	ISO8601	Dernier démarrage de lecture.

Marketplace

À renseigner si votre produit est une plateforme à deux versants.

Clé	Type	Description
`$seller_tier`	chaîne de caractères	Slug du palier côté vendeur.
`$buyer_tier`	chaîne de caractères	Slug du niveau côté acheteur.
`$listings_count`	nombre	Annonces actives appartenant à l’utilisateur.
`$reviews_count`	nombre	Avis reçus par l’utilisateur.
`$verified`	booléen	Statut KYC.

Fidélité

À renseigner pour les programmes d’engagement et de récompenses.

Clé	Type	Description
`$loyalty_points`	nombre	Solde actuel des points échangeables.
`$vip_level`	chaîne de caractères	Slug du palier VIP.
`$referral_count`	nombre	Parrainages réussis attribués à cet utilisateur.

Conseil

Vous ne trouvez pas votre cas ? Utilisez des clés simples pour les attributs personnalisés. Elles apparaissent dans le panneau Custom Traits du dashboard sans encombrer les colonnes de profil. Les 5 ensembles sectoriels ci-dessus reflètent les structures B2B les plus courantes — la terminologie propre à chaque client (par ex. shipping_plan) doit rester en clé simple.

Super-propriétés

Paires clé/valeur propres à la session, ajoutées automatiquement à chaque événement sortant. Contrairement aux attributs identify(), qui décrivent l’identité, les super-propriétés décrivent le contexte de la session : variante A/B active, variante de build, feature flags activés, référence d’affiliation. Elles sont conservées dans localStorage entre les rechargements, puis effacées lors de reset(). En cas de collision de clé, les properties définies sur l’événement dans track() priment toujours.

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

Cartes de chaleur

L’enregistrement des cartes thermiques est activé par défaut : clics et profondeur de défilement, tous deux échantillonnés à 100 %. Le suivi des mouvements de souris est optionnel (volumétrie élevée ; activez-le page par page si utile).

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

Replay de session

Le replay de session enregistre un instantané du DOM via rrweb ainsi qu’un flux de mutations, afin que le dashboard puisse reconstruire la page sous forme de session navigable avec sa chronologie d’événements. Il s’agit d’une reconstruction du DOM, et non d’un enregistrement vidéo de l’écran. Replay est désactivé par défaut. Activez-le pour le projet dans Dashboard → Settings → Relecture de session ; aucune modification du code de l’application n’est nécessaire. Une fois activé, l’enregistreur est chargé depuis un chunk séparé de version correspondante.

Remarque

Le dashboard fait foi. Définissez-y Enable replay, Mask inputs, la durée maximale et les contrôles avancés de capture. captureOnCellular est stocké dans la même politique de projet pour iOS et Android ; les navigateurs n’exposent pas de signal fiable pour distinguer le Wi‑Fi du réseau cellulaire, donc le SDK Web signale cette restriction propre au natif puis l’ignore.

Ce qui est masqué

Replay est conçu pour pouvoir être activé en toute sécurité. Trois couches protègent les contenus sensibles, toutes activées par défaut :

Le masquage des champs est défini au niveau du projet — tant que le paramètre Masquer les champs de saisie du Dashboard est activé (par défaut), les caractères saisis sont remplacés par des astérisques avant de quitter le navigateur. Désactivez-le uniquement pour un besoin précis et peu sensible ; les champs d’identité, d’authentification et de paiement restent masqués.
L’attribut data-kixo-mask masque un élément et tout son sous-arbre. Ajoutez-le à tout conteneur susceptible de contenir des données personnelles ou confidentielles ; la relecture affiche un espace réservé, sans le texte ni le contenu DOM de ce sous-arbre.
html
```
<div data-kixo-mask>
  
  
</div>
```
Les champs sensibles sont toujours masqués — les champs qui ressemblent à un mot de passe, un numéro de carte, un CVV, un SSN, un secret ou un token (d’après leur type, name, id ou autocomplete) sont masqués même si le paramètre Masquer les champs de saisie du projet est désactivé. Le texte visible et les attributs DOM sérialisés passent aussi par le filtre PII de Kixo avant l’envoi.

Collecte de données

Le SDK collecte les traceurs activés dans votre intégration et dans les paramètres du projet, ainsi que les événements et propriétés envoyés par votre application.

Destination des enregistrements

Le SDK compresse les événements rrweb avec gzip en segments de taille bornée, demande à Kixo une URL d’envoi signée limitée au projet, puis envoie directement ces segments vers le stockage du replay. Ouvrez la session reconstruite dans Replay → Sessions : elle renvoie vers la trace analytique de cette même session.

Remarque

Replay dépend de votre offre. Le nombre de sessions capturées et conservées dépend de votre offre ; sur les offres inférieures, Kixo enregistre tout de même des métadonnées de session légers pour que la session apparaisse dans vos listes et vos analyses.

Feature flags

Vérifiez les valeurs des flags à l’exécution avec Kixo.getFeatureFlag().

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

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

Envoi et comportement hors ligne

Le SDK met les événements en file d’attente localement, les envoie par lots et réessaie les échecs temporaires avec temporisation exponentielle. Si la collecte est suspendue dans les paramètres du projet, les nouveaux événements ne sont plus envoyés tant qu’elle n’est pas réactivée.

Diagnostic

Instantané d’état en lecture seule, utile dans les outils de développement pour comprendre pourquoi les événements ne remontent pas.

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