renaud/espace-paie-odentas
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
espace-paie-odentas/POSTHOG_ANALYTICS_GUIDE.md

9.3 KiB
Raw Blame History

📊 PostHog Analytics - Guide d'Utilisation

🎯 Vue d'ensemble

PostHog est configuré pour tracker automatiquement les événements utilisateurs dans l'application Odentas Espace Paie.

✅ Configuration actuelle

Installation

  • Package : posthog-js (client) + posthog-node (serveur)
  • Région : EU (https://eu.i.posthog.com)
  • Variables d'environnement :
    • NEXT_PUBLIC_POSTHOG_KEY : Clé API publique
    • NEXT_PUBLIC_POSTHOG_HOST : URL du serveur PostHog

Composants créés

  1. PostHogProvider (components/PostHogProvider.tsx)

    • Initialise PostHog au chargement de l'application
    • Active le mode debug en développement
    • Expose window.posthog pour les tests console en dev
    • Important : Utilise person_profiles: 'identified_only' - les utilisateurs ne sont créés dans PostHog que lorsqu'ils sont explicitement identifiés

  2. PostHogPageView (components/PostHogPageView.tsx)

    • Track automatiquement chaque changement de page
    • Capture l'URL complète avec query params

  3. PostHogIdentifier (components/PostHogIdentifier.tsx)

    • Composant clé pour l'identification des utilisateurs ⭐
    • Identifie automatiquement les utilisateurs connectés via l'API /api/me
    • Associe les propriétés utilisateur (email, nom, company, etc.)
    • Réinitialise l'identité lors de la déconnexion
    • Note : Si vous ne voyez pas les utilisateurs identifiés dans PostHog, vérifiez que ce composant est bien présent dans votre layout

🔍 Pourquoi les utilisateurs sont anonymes ?

Si vous voyez tous les utilisateurs anonymisés dans PostHog, c'est probablement parce que :

  1. ❌ Le composant PostHogIdentifier n'est pas présent dans le layout
  2. ❌ L'API /api/me ne retourne pas les bonnes données (vérifiez la structure JSON)
  3. ❌ L'utilisateur n'est pas authentifié au moment où PostHog charge
  4. ❌ Les variables d'environnement PostHog sont manquantes

Solution :

  • Vérifiez que <PostHogIdentifier /> est bien dans app/layout.tsx
  • Ouvrez la console du navigateur et regardez les logs : vous devriez voir 👤 PostHog: Utilisateur identifié: email@example.com
  • Si vous voyez une erreur, vérifiez que l'API /api/me fonctionne correctement

📈 Événements trackés automatiquement

Événements système

  • $pageview : Chaque changement de page
  • $pageleave : Quand l'utilisateur quitte une page
  • $autocapture : Clics et interactions (si activé)

Propriétés utilisateur trackées

Lors de l'identification (connexion) :

  • email : Email de l'utilisateur
  • first_name : Prénom
  • display_name : Nom d'affichage complet
  • company_name : Nom de la société active (active_org_name)
  • company_id : ID de la société active (active_org_id)
  • is_staff : Membre du staff ou non

🔧 Utilisation avancée

Tracker un événement personnalisé

'use client';
import { usePostHog } from 'posthog-js/react';

function MonComposant() {
  const posthog = usePostHog();

  const handleAction = () => {
    posthog.capture('nom_evenement', {
      propriete1: 'valeur',
      propriete2: 123,
      timestamp: new Date().toISOString()
    });
  };

  return <button onClick={handleAction}>Action</button>;
}

Exemple concret : Tracking de création de contrat ✨

// Après création réussie d'un contrat
posthog?.capture('contract_created', {
  contract_type: 'CDDU',
  regime: 'CDDU_MONO',
  categorie_professionnelle: 'Artiste',
  contract_id: contractId,
  validation_immediate: true,
});

💡 Voir le guide complet : POSTHOG_SURVEY_CONTRATS.md pour la mise en place d'un survey de satisfaction après création de contrats.

Identifier un utilisateur manuellement

posthog.identify('user_id_unique', {
  email: 'user@example.com',
  name: 'Nom Utilisateur',
  plan: 'premium'
});

Tracker une propriété super (persistante)

// Sera ajoutée à tous les événements futurs
posthog.register({
  app_version: '1.0.0',
  environment: 'production'
});

Réinitialiser l'identité

// À la déconnexion (déjà fait dans LogoutButton)
posthog.reset();

🧪 Tests en développement

Console du navigateur

En mode développement, PostHog est accessible via window.posthog :

// Tester un événement
window.posthog.capture('test_event', { message: 'Hello' });

// Voir l'utilisateur actuel
window.posthog.get_distinct_id();

// Voir les propriétés
window.posthog.get_property('email');

Vérifier les requêtes réseau

  1. Ouvrez DevTools (F12)
  2. Onglet Network
  3. Filtrez par "batch" ou "posthog"
  4. Les requêtes vers eu.i.posthog.com/batch/ doivent être en status 200

Logs console

Avec le mode debug activé, vous verrez :

[PostHog.js] "capture" {event: "$pageview", properties: {...}}
[PostHog.js] "identify" {distinctId: "user_id", properties: {...}}

📊 Dashboard PostHog

Accès

https://eu.posthog.com/

Vues utiles

  1. Activity / Live Events : Voir les événements en temps réel
  2. Persons : Liste des utilisateurs identifiés
  3. Insights : Créer des graphiques et analyses
  4. Funnels : Analyser les parcours utilisateurs
  5. Session Recordings : Voir les replays de sessions (si activé)

Filtres utiles

  • Exclure dev : $current_url does not contain localhost
  • Voir uniquement staff : is_staff = true
  • Par société : company_name = X

🎯 Cas d'usage recommandés

1. Tracker les actions importantes

// Création d'un contrat
posthog.capture('contrat_created', {
  contrat_id: contratId,
  type: typeContrat,
  montant: montant
});

// Signature d'un document
posthog.capture('document_signed', {
  document_type: 'contrat',
  document_id: docId
});

// Téléchargement de fiche de paie
posthog.capture('payslip_downloaded', {
  month: '2025-10',
  employee_id: employeeId
});

2. Groupes (pour analytics par société)

posthog.group('company', companyId, {
  company_name: 'Société X',
  plan: 'premium',
  employees_count: 50
});

3. Feature Flags (A/B testing)

const showNewFeature = posthog.isFeatureEnabled('new_ui_design');

if (showNewFeature) {
  // Afficher la nouvelle interface
}

🔒 Confidentialité & RGPD

Données collectées

  • Événements de navigation et interactions
  • Propriétés utilisateur (email, nom, société)
  • Données techniques (navigateur, OS, résolution)

Données NON collectées par défaut

  • Mots de passe
  • Données sensibles dans les formulaires
  • Contenu des documents

Respect du RGPD

  • Hébergement EU (GDPR compliant)
  • Possibilité d'anonymiser les IPs
  • Droit à l'oubli via l'API PostHog

Opt-out utilisateur

// Si l'utilisateur refuse le tracking
posthog.opt_out_capturing();

// Pour réactiver
posthog.opt_in_capturing();

🚨 Troubleshooting

Les événements n'arrivent pas

  1. ✅ Vérifier que les variables NEXT_PUBLIC_* sont dans .env.local
  2. ✅ Redémarrer le serveur après modification du .env.local
  3. ✅ Vérifier la console : doit afficher "✅ PostHog initialisé"
  4. ✅ Vérifier Network : requêtes /batch/ en status 200
  5. ✅ Vérifier la clé API dans le dashboard PostHog

❌ Les utilisateurs sont tous anonymes / non identifiés

Symptôme : Dans PostHog, vous voyez des utilisateurs avec des IDs anonymes (ex: anon_xyz123) au lieu des vrais utilisateurs.

Cause : Le composant PostHogIdentifier n'identifie pas correctement les utilisateurs.

Solutions :

  1. Vérifier la console du navigateur :

    • Vous devriez voir : 👤 PostHog: Utilisateur identifié: email@example.com ID: user-uuid
    • Si vous voyez une erreur, notez le message

  2. Vérifier que PostHogIdentifier est dans le layout :

    • Ouvrir app/layout.tsx
    • Chercher <PostHogIdentifier />
    • Doit être à l'intérieur du <Providers> ou <PostHogProvider>

  3. Tester l'API /api/me :

    # Dans la console du navigateur (quand vous êtes connecté)
fetch('/api/me').then(r => r.json()).then(console.log)
    • Doit retourner : { user: { id: "...", email: "..." }, active_org_id: "...", ... }
    • Si user.id est undefined, il y a un problème avec l'API

  4. Vérifier la configuration PostHog :

    • Dans PostHogProvider.tsx, vous devez avoir : person_profiles: 'identified_only'
    • Cela signifie que PostHog ne crée des profils que pour les utilisateurs identifiés explicitement

  5. Forcer une réidentification :

    // Dans la console du navigateur
window.posthog.reset(); // Efface l'identité actuelle
window.location.reload(); // Recharge la page pour réidentifier

Double initialisation

Si vous voyez "You have already initialized PostHog!", c'est normal en dev (React Strict Mode). En production, cela n'arrive pas.

Événements en retard

PostHog batch les événements pour optimiser les performances. Ils peuvent apparaître avec 5-30s de délai dans le dashboard.

📚 Ressources

Dernière mise à jour : 13 octobre 2025