espace-paie-odentas/POSTHOG_ANALYTICS_GUIDE.md

# 📊 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é

```tsx
'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** ✨

```tsx
// 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

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

### Tracker une propriété super (persistante)

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

### Réinitialiser l'identité

```typescript
// À 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` :

```javascript
// 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

```typescript
// 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é)

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

### 3. Feature Flags (A/B testing)

```typescript
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

```typescript
// 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** :
   ```bash
   # 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** :
   ```javascript
   // 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

- [Documentation PostHog](https://posthog.com/docs)
- [API JavaScript](https://posthog.com/docs/libraries/js)
- [React Integration](https://posthog.com/docs/libraries/react)
- [Feature Flags](https://posthog.com/docs/feature-flags)

---

**Dernière mise à jour** : 13 octobre 2025