tracker

Tracker SDK est une bibliothèque d'analytique web de taille réduite, conçue pour une intégration rapide dans les applications modernes, en particulier celles générées par des outils assistés par IA comme le Vibe Coding. Elle mise sur la simplicité : un seul appel `init` configure le point de collecte, après quoi les pagesviews sont enregistrées automatiquement et les événements personnalisés peuvent être envoyés avec `track(eventName, data)`. **Fonctionnalités clés** - **Démarrage sans configuration** – Ajouter une balise script ou un import npm suffit pour commencer la collecte. - **Détection automatique des pagesviews** – Le SDK écoute les événements de navigation et envoie un payload `pageview` sans code supplémentaire. - **Suivi d'événements personnalisés** – Les développeurs peuvent enregistrer n'importe quelle interaction en appelant `track` avec un nom et un payload optionnel. - **Empreinte numérique** – Une empreinte basée sur le canvas identifie de manière unique les visiteurs tout en respectant la vie privée. - **File d'attente hors ligne** – Les événements non envoyés sont stockés dans le stockage local et réessayés ultérieurement, minimisant ainsi la perte de données. - **Gestion des sessions** – Les sessions sont créées automatiquement et expirent après un délai configurable (défaut 30 minutes). - **Regroupement configurable** – Les événements sont regroupés en une seule requête pour réduire la charge réseau. **Installation** - **CDN** – Inclure le bundle UMD directement dans le HTML et appeler `WFTK.init({ endpoint: 'https://your-api.com/api/v1/collect/event', debug: true })`. - **npm** – `npm install @weavefox/tracker` puis importer les fonctions : `import { init, track, setUserId } from '@weavefox/tracker';`. **API publique** | Méthode | Objectif | |---------|----------| | `init(config)` | Initialiser le SDK avec le point de terminaison, appId et drapeaux optionnels. | | `track(eventName, data)` | Envoyer un événement personnalisé. | | `trackPageview(data)` | Enregistrer manuellement une pageview (activé par défaut). | | `setUserId(userId)` | Associer un utilisateur connecté aux événements ultérieurs. | | `getFingerprint()` | Récupérer l'empreinte numérique générée. | | `flush()` | Diffuser immédiatement tous les événements en attente. | **Options de configuration** ```javascript WFTK.init({ endpoint: 'required', // URL du service de collecte appId: 'optional', // Identifiant de l'application autoPageview: true, // Suivi automatique des pagesviews debug: false, // Activer le débogage console enableQueue: true, // Stocker les événements hors ligne en cas d'erreur réseau sessionTimeout: 1800000, // Délai d'inactivité de session en ms (défaut 30 min) maxEventsPerSession: 1000 // Limite supérieure d'événements par session }); ``` **Format du payload** – Chaque requête contient un corps JSON avec un `appId` optionnel et un tableau `events`. Chaque événement comprend un nom `event` obligatoire, `timestamp`, `nonce` (pour le dédupliquage), `fingerprint`, et un objet `data` avec le contexte collecté par le système (URL, titre, informations appareil, etc.). Les champs définis par l'utilisateur appartiennent au sous-objet `biz`, séparant ainsi les données analytiques des données métier. **Considérations côté serveur** - **Validation des horodatages** – Rejeter les événements âgés de plus de 5 minutes pour prévenir les attaques par rejeu. - **Dédupliquage des nonces** – Stocker les nonces (par ex. dans Redis) avec un TTL de 24 heures pour garantir l'idempotence. - **Limitation du débit** – Appliquer des limites par IP et par empreinte pour limiter les abus. - **Identification de l'application** – Privilégier un `appId` explicite dans le payload ; utiliser le `Referer` host comme solution de repli si nécessaire. - **Exemple de handler Express** – Le README fournit un extrait Node.js concis qui valide les horodatages, vérifie les nonces et persiste les événements. **Licence** – Distribué sous la licence MIT, permettant une utilisation sans restriction dans les projets open-source et commerciaux. En résumé, Tracker SDK propose une solution simple et respectueuse de la vie privée pour les développeurs qui ont besoin d'une analytique côté client fiable, sans la surcharge des plateformes lourdes.