Tracking NPM

🤷 Le problème

Vous publiez sur NPM. Vous avez des statistiques de téléchargements, mais vous ne savez pas vraiment :

• 🤷 Qui utilise réellement votre package en production
• 🌐 Sur quels sites web il tourne
• 📊 Quelles versions sont déployées sur le terrain
• ⚠️ Combien de sites utilisent des versions obsolètes

De plus, ces statistiques ne trackent pas les utilisateurs finaux, seulement les développeurs qui installent le package.

✅ La solution : Tracking NPM

Tracking NPM est un système léger et automatique qui vous donne une visibilité complète sur l'utilisation réelle de votre package JavaScript dans les navigateurs.

📦 Ce que vous obtenez

🔧 Comment ça marche ? Intégration simple (2 minutes)

Étape 1 : Connectez-vous via GitHub — c'est gratuit & rapide

Oui, sinon impossible de vérifier la propriété du package !

Rendez-vous dans Licence > Tracking NPM, puis ajoutez vos packages.
Tous les formats de noms npm sont acceptés :

• @votre-scope/votre-package — format scopé (recommandé)
• votre-package — format classique (non scopé)
• @organisation/module-tracking — pour les packages d'entreprise
• @synapxlab/cookie-consent — exemple de package public
• mon-module-local — pour un package privé ou local

Tracking NPM génère une clé unique par package à copier/coller dans votre librairie.

Étape 2 : Intégrez le script Tracking NPM dans votre package

npm install @synapxlab/tracking-npm

// --- Initialisation du Tracking NPM ---
import '@synapxlab/tracking-npm';

if (window.trackingnpm?.init) {
  window.trackingnpm.version = '2.4.0'; // 🔢 Version de votre package (optionnel)
  window.trackingnpm.package_key = 'NPM_XXXXXXXXXXX'; // 📦 Clé unique générée dans l'espace membre (obligatoire)
  window.trackingnpm.init();
}

Étape 3 : C'est tout ! Le reste est entièrement automatique.

Fonctions additionnelles (optionnelles)

// 🎲 Fréquence d'échantillonnage (1 à 100) — 10% par défaut
window.trackingnpm.scale = 10; 

// ⏱️ Délai avant exécution (en millisecondes)
// Permet de différer le check pour ne pas bloquer le chargement
// 10 secondes par défaut
window.trackingnpm.delay = 10_000;

// 🧠 Mode debug — active des logs console
window.trackingnpm.debug = false;

Fonctionnement discret

Ça ralentit les sites ? Non. Exécution en idle time, après 10s, pour seulement 10% des visiteurs. Impact : ~0ms.

• ⏱️ Différé : attend 10 secondes après le chargement
• ⚡ Non bloquant : s'exécute pendant les périodes d'inactivité
• 🎲 Échantillonnage : seulement 10% des visiteurs
• 🚫 Respectueux : s'annule si l'onglet devient inactif ou se ferme

Objectif : Faire le moins d'appels possible, mais au moins 1 par semaine pour confirmer l'activité du site.

💼 Cas d'usage concrets

🚀 Commencer maintenant

1️⃣ Créez votre compte

Connectez-vous via GitHub sur http://synapx.fr/sdk/tracking/

2️⃣ Installation

npm install @synapxlab/tracking-npm

3️⃣ Configuration

import '@synapxlab/tracking-npm';

if (window.trackingnpm?.init) {
  window.trackingnpm.version = '2.5.0';
  window.trackingnpm.package_key = 'NPM_XXXXXXXXXXX'; // Votre clé unique
  window.trackingnpm.init();
}

4️⃣ Publiez votre package

Publiez la nouvelle version sur NPM. Les sites qui utilisent votre package commenceront à apparaître dans votre dashboard sous 24-48h.

⚡ Download

{
    "package": "@synapxlab\/cookie-consent",
    "sk_live": "8c0cf425d8bf3a7a5591d41916ba4357bf5f48d6ea5fe9e5e5c6ab98eb7cec7c",
    "total_hosts": 12,
    "hosts": [
        {
            "host": "example.com",
            "version": "2.1.3"
            "last_ping": "2025-10-27 09:12:00"
            "total_pings": 5
        },
        {
            "host": "autre-site.fr",
            "version": "2.1.3"
            "last_ping": "2025-10-27 09:12:00"
            "total_pings": 15
        }
        ...
    ]
}

⚡ Performance & Scalabilité

Impact minimal sur les utilisateurs finaux

• ~3KB gzippé pour le tracker
• 0ms de blocking time (idle execution)
• 10% sampling par défaut = 90% des visiteurs non impactés
• 10 secondes d'attente minimum avant le check
• Impossible de faire ralentir ou planter votre package (silent fail)

🔍 Pourquoi l'échantillonnage aléatoire suffit ?

🔒 RGPD & Respect de la vie privée

✅ RGPD-friendly

• ❌ Aucun cookie posé
• ❌ Aucune donnée utilisateur final collectée
• ❌ Aucune IP personnelle stockée (anonymisation serveur)
• ✅ Seulement le domaine du site (information publique)
• ✅ Données privées accessibles uniquement au propriétaire du package
• ✅ Serveurs hébergés en France (OVH Roubaix)
• ✅ Rétention des données : 90 jours maximum

🛡️ Ce que nous collectons (exhaustif)

{
  "package_key": "NPM_a1b2c3d4e5f6",
  "version": "2.5.0",
}

C'est TOUT. Aucune autre donnée n'est transmise ou stockée.

🔐 Politique de confidentialité

• ✅ HTTPS uniquement (TLS 1.3)
• ✅ Vérification de propriété du package via GitHub/NPM
• ✅ Clé unique par package (non devinable)
• ✅ Rate limiting côté serveur (1 ping/heure max par domaine)
• ✅ Pas d'exécution de code distant
• ✅ Open source (code auditable)

Ce que nous NE collectons PAS

4. Base légale (RGPD)

Le traitement repose sur l'intérêt légitime du mainteneur du package NPM (Article 6.1.f du RGPD).

5. Qui a accès aux données ?

🛠️ Développement

git clone https://github.com/synapxLab/tracking_npm.git
cd tracking_npm
npm install
npm run dev     # Serveur de développement
npm run build   # Build production minifié

🤝 Contribuer

Les contributions sont les bienvenues ! Consultez le dépôt GitHub pour :

• 🐛 Reporter des bugs
• 💡 Proposer des améliorations
• 📖 Améliorer la documentation
• 🔧 Soumettre des pull requests

📜 Licence

MIT – Utilisez, modifiez, redistribuez librement. Merci de conserver la mention de licence.

Code source disponible sur GitHub.