Ce guide explique comment installer et utiliser le SDK Clickstream SurveyAnalytica sur des projets web. Le SDK est publié sur npm et fonctionne dans tout environnement JavaScript, y compris Vanilla JS, Next.js et React. Pour les applications mobiles, consultez le guide des SDK mobiles.

Avant de commencer, effectuez la configuration du workflow pour obtenir votre clé API et votre URL de point de terminaison.

Installation

Sites Vanilla JS / HTML

Incluez le bundle UMD directement dans votre page. Aucune étape de build n’est nécessaire.

<script src="https://cdn.jsdelivr.net/npm/@surveyanalytica/clickstream-web/dist/index.umd.js"></script>
<script>
  SAClickstream.init('YOUR_WORKFLOW_ID', 'YOUR_API_KEY', {
    endpoint: 'YOUR_ENDPOINT_URL'
  });
</script>

Projets npm (Next.js, React, etc.)

npm install @surveyanalytica/clickstream-web

Puis initialisez une seule fois, au point d’entrée de votre application :

import { SAClickstream } from '@surveyanalytica/clickstream-web';

SAClickstream.init('YOUR_WORKFLOW_ID', 'YOUR_API_KEY', {
  endpoint: 'YOUR_ENDPOINT_URL'
});

Pour Next.js, appelez init à l’intérieur d’un Client Component ou dans _app.js / layout.js. Le SDK est compatible avec le rendu côté serveur — tout accès aux API du navigateur est protégé en interne.

Suivi des pages vues

Le SDK suit automatiquement les pages vues. À chaque changement d’URL (y compris la navigation en page unique via l’API History), un événement page_view est envoyé avec l’URL actuelle, le titre de la page et le référent. Aucun code n’est nécessaire au-delà de l’appel à init.

Pour envoyer une page vue manuellement :

SAClickstream.page('/checkout', { campaign: 'summer-sale' });

Suivi des événements personnalisés

SAClickstream.track('button_clicked', {
  label: 'Buy Now',
  productId: 'sku-9821',
  price: 49.99
});

Les valeurs de propriété peuvent être des chaînes, des nombres, des booléens ou des objets imbriqués. Gardez des noms d’événements courts et cohérents dans l’ensemble de votre code (par exemple, utilisez toujours button_clicked plutôt que de mélanger buttonClick et btn_tap).

Identification des utilisateurs après connexion

Avant la connexion, le SDK attribue à chaque visiteur un ID anonyme aléatoire stocké dans localStorage. Après la connexion, appelez identify avec l’ID de contact provenant de votre backend :

// After a successful login
SAClickstream.identify('contact-id-from-your-backend');

Cela envoie un événement uid_transition reliant la session anonyme au contact connu. Les événements enregistrés avant la connexion sont associés au contact via l’ID anonyme stocké sur la fiche du contact — aucune donnée n’est perdue.

Gestion du consentement

Si votre site utilise une bannière de consentement aux cookies, respectez le choix de l’utilisateur :

// User accepted tracking
SAClickstream.setConsent(true);

// User declined tracking
SAClickstream.setConsent(false);

Lorsque le consentement est défini sur false, le suivi s’arrête immédiatement et l’association de l’ID anonyme est effacée. Aucun autre événement n’est envoyé tant que le consentement n’est pas de nouveau accordé.

Comment les événements sont envoyés

Le SDK regroupe les événements et les envoie toutes les 500 millisecondes, ou immédiatement lorsque 20 événements se sont accumulés. Les requêtes échouées sont réessayées jusqu’à trois fois avec des délais croissants. Cela permet de maintenir une faible utilisation du réseau sans perdre d’événements lors de problèmes de connectivité temporaires.

Dépannage

Les événements n’apparaissent pas dans mon workflow

• Vérifiez que le workflow est à l’état Actif.
• Vérifiez la console du navigateur pour détecter d’éventuelles erreurs réseau sur les requêtes vers votre URL de point de terminaison.
• Vérifiez que la clé API correspond à la clé (KEY) affichée dans le tiroir du déclencheur — copiez-collez plutôt que de la saisir.
• Assurez-vous que init est appelé avant tout appel à track ou page.

Des pages vues en double sont enregistrées

Si vous appelez SAClickstream.page() manuellement en plus du suivi automatique, vous verrez deux événements par navigation. Désactivez soit le suivi automatique (autoPage: false dans les options d’init), soit supprimez vos appels manuels à page().