espace-paie-odentas/SIMULATEUR_POSTHOG_TRACKING.md

# 📊 Tracking PostHog du Simulateur de Paie

## Vue d'ensemble

Le simulateur de paie envoie maintenant un événement PostHog à chaque fois qu'un utilisateur clique sur le bouton "Calculer". Cet événement permet de déclencher des surveys et d'analyser l'utilisation du simulateur.

## Architecture

### Communication iframe → parent
Le simulateur est intégré via une iframe (`/simulateur-embed.html`). Pour envoyer des événements PostHog :

1. **L'iframe** envoie un message via `postMessage` au clic sur "Calculer"
2. **La page parent** (`app/(app)/simulateur/page.tsx`) écoute ce message
3. **La page parent** envoie l'événement à PostHog avec le hook `usePostHog`

### Schéma
```
simulateur-embed.html (iframe)
    │
    │ postMessage({ type: 'simulateur_calculation', data: {...} })
    │
    ▼
simulateur/page.tsx (parent)
    │
    │ window.addEventListener('message', ...)
    │
    ▼
PostHog
```

## Événement envoyé

### Nom de l'événement
`simulateur_calculation`

### Propriétés complètes
| Propriété | Type | Description | Exemple |
|-----------|------|-------------|---------|
| **Paramètres du formulaire** ||||
| `ccn_id` | string | ID de la CCN sélectionnée | `"1285"` |
| `ccn_nom` | string | Nom complet de la CCN | `"1285 – Entreprises Artistiques & Culturelles (CCNEAC)"` |
| `categorie` | string | Catégorie du salarié | `"artiste"` ou `"technicien"` |
| `statut` | string | Statut professionnel | `"non-cadre"` ou `"cadre"` |
| `abattement_active` | boolean | Abattement pour frais pro activé | `true` ou `false` |
| `abattement_profession` | string | Type de profession (si abattement) | `"drama"`, `"musique"` ou `""` |
| **Cachets, heures et dates** ||||
| `cachets` | number | Nombre de cachets | `10` |
| `heures` | number | Nombre d'heures | `35` |
| `dates_travail` | array | Liste des dates de travail | `["2025-10-15", "2025-10-16"]` |
| `nombre_jours` | number | Nombre de jours travaillés | `2` |
| **Montant et type de calcul** ||||
| `montant_saisi` | number | Montant saisi par l'utilisateur | `2000` |
| `type_calcul` | string | Type de calcul effectué | `"brut"`, `"net"` ou `"cost"` |
| **Résultats calculés** ||||
| `resultat_brut` | number | Salaire brut calculé | `2000.00` |
| `resultat_net` | number | Salaire net avant PAS calculé | `1580.50` |
| `resultat_cost` | number | Coût total employeur calculé | `2456.80` |
| **Métadonnées** ||||
| `plafond_urssaf` | number | Plafond URSSAF appliqué | `3864` |
| `timestamp` | string | Date/heure de la simulation | `"2025-10-16T14:30:00.000Z"` |

### Exemple d'événement complet
```javascript
{
  event: 'simulateur_calculation',
  properties: {
    // Paramètres du formulaire
    ccn_id: '1285',
    ccn_nom: '1285 – Entreprises Artistiques & Culturelles (CCNEAC)',
    categorie: 'artiste',
    statut: 'non-cadre',
    abattement_active: true,
    abattement_profession: 'drama',
    
    // Cachets, heures et dates
    cachets: 10,
    heures: 35,
    dates_travail: ['2025-10-15', '2025-10-16', '2025-10-17'],
    nombre_jours: 3,
    
    // Montant et type de calcul
    montant_saisi: 2000,
    type_calcul: 'brut',
    
    // Résultats calculés
    resultat_brut: 2000.00,
    resultat_net: 1580.50,
    resultat_cost: 2456.80,
    
    // Métadonnées
    plafond_urssaf: 3864,
    timestamp: '2025-10-16T14:30:00.000Z'
  }
}
```

## Fichiers modifiés

### 1. `/public/simulateur-embed.html`
**Ligne 1326+** : Ajout de l'envoi du message enrichi via `postMessage` dans le gestionnaire du bouton "Calculer"

```javascript
// 📊 Envoyer un événement PostHog enrichi via postMessage au parent
try {
  // Récupération de toutes les données du formulaire
  const ccnElement = document.getElementById('conventionSelect');
  const ccnValue = ccnElement?.value || '';
  const ccnText = ccnElement?.options[ccnElement.selectedIndex]?.text || '';
  
  const categorieValue = isTechnicien() ? 'technicien' : 'artiste';
  const statutValue = document.getElementById('statutSelect')?.value || 'non-cadre';
  
  // Abattement
  const abattementChecked = document.querySelector('input[name="abattement"]:checked')?.value || 'non';
  const professionValue = document.getElementById('professionSelect')?.value || '';
  
  // Dates
  const datesInput = document.getElementById('datesInput')?.value || '';
  const datesArray = datesInput ? datesInput.split(',').map(d => d.trim()).filter(Boolean) : [];
  
  window.parent.postMessage({
    type: 'simulateur_calculation',
    data: {
      // Paramètres du formulaire
      ccn_id: ccnValue,
      ccn_nom: ccnText,
      categorie: categorieValue,
      statut: statutValue,
      abattement_active: abattementChecked === 'oui',
      abattement_profession: professionValue,
      
      // Cachets, heures, dates
      cachets: cachets,
      heures: heures,
      dates_travail: datesArray,
      nombre_jours: datesArray.length,
      
      // Montant saisi et type
      montant_saisi: montant,
      type_calcul: type,
      
      // Résultats calculés
      resultat_brut: parseFloat(brut.toFixed(2)),
      resultat_net: parseFloat(net.toFixed(2)),
      resultat_cost: parseFloat(costEmployer.toFixed(2)),
      
      // Métadonnées
      plafond_urssaf: plafondUrssaf,
      timestamp: new Date().toISOString()
    }
  }, '*');
} catch (e) {
  console.error('Erreur lors de l\'envoi de l\'événement PostHog:', e);
}
```

### 2. `/app/(app)/simulateur/page.tsx`
**Lignes 12-50** : Mise à jour du hook PostHog pour capturer toutes les propriétés enrichies

```typescript
useEffect(() => {
  const handleMessage = (event: MessageEvent) => {
    if (event.data?.type === 'simulateur_calculation') {
      const data = event.data.data;
      
      posthog?.capture('simulateur_calculation', {
        // Paramètres du formulaire
        ccn_id: data.ccn_id,
        ccn_nom: data.ccn_nom,
        categorie: data.categorie,
        statut: data.statut,
        abattement_active: data.abattement_active,
        abattement_profession: data.abattement_profession,
        
        // Cachets, heures, dates
        cachets: data.cachets,
        heures: data.heures,
        dates_travail: data.dates_travail,
        nombre_jours: data.nombre_jours,
        
        // Montant saisi et type
        montant_saisi: data.montant_saisi,
        type_calcul: data.type_calcul,
        
        // Résultats calculés
        resultat_brut: data.resultat_brut,
        resultat_net: data.resultat_net,
        resultat_cost: data.resultat_cost,
        
        // Métadonnées
        plafond_urssaf: data.plafond_urssaf,
        timestamp: data.timestamp
      });
    }
  };

  window.addEventListener('message', handleMessage);
  return () => window.removeEventListener('message', handleMessage);
}, [posthog]);
```

    window.addEventListener('message', handleMessage);
    return () => window.removeEventListener('message', handleMessage);
  }, [posthog]);
  
  // ... reste du composant
}
```

## Utilisation pour les surveys

### Créer un survey dans PostHog

1. **Se connecter à PostHog** : https://eu.posthog.com/
2. **Aller dans Surveys** → **New Survey**
3. **Configurer le targeting** :
   - Type : Popover
   - Trigger : `simulateur_calculation` (l'événement que nous envoyons)
   - Display conditions : Par exemple après 1 calcul, ou après 3 calculs, etc.

### Exemple de configuration
```
Targeting:
- Show when: simulateur_calculation event occurs
- Frequency: Once per user / Every time
- Wait period: 0 seconds (ou délai souhaité)
```

### Questions suggérées
- "Le simulateur vous a-t-il été utile ?"
- "Quelle fonctionnalité aimeriez-vous voir ajoutée ?"
- "Avez-vous trouvé les résultats clairs ?"

## Vérification

### Dans la console du navigateur
Lors d'un clic sur "Calculer", vous devriez voir :
```
📊 PostHog: Événement simulateur_calculation enrichi envoyé {
  categorie: 'artiste',
  ccn: '1285 – Entreprises Artistiques & Culturelles (CCNEAC)',
  type_calcul: 'brut',
  montant_saisi: 2000,
  resultats: {
    brut: 2000,
    net: 1580.5,
    cost: 2456.8
  }
}
```

### Dans PostHog
1. Aller dans **Activity** → **Live Events**
2. Filtrer par événement : `simulateur_calculation`
3. Vérifier que les propriétés sont correctes

## Dépannage

### L'événement n'apparaît pas dans PostHog
1. Vérifier que PostHog est bien initialisé dans l'app
2. Vérifier les variables d'environnement :
   ```bash
   NEXT_PUBLIC_POSTHOG_KEY=phc_...
   NEXT_PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com
   ```
3. Activer le mode debug de PostHog dans la console :
   ```javascript
   window.posthog.debug(true)
   ```

### Le message postMessage n'arrive pas
1. Vérifier que l'iframe est bien chargée
2. Vérifier dans la console qu'il n'y a pas d'erreur CORS
3. Tester en console :
   ```javascript
   window.addEventListener('message', (e) => console.log('Message reçu:', e.data));
   ```

## Évolutions futures

### Analyses possibles avec les données enrichies
Avec toutes ces propriétés, vous pouvez maintenant analyser :

- **Par CCN** : Quelle convention collective est la plus utilisée ?
- **Par catégorie** : Artiste vs Technicien - ratio d'utilisation
- **Par type de calcul** : Les utilisateurs partent-ils plutôt du brut, net ou coût ?
- **Abattement** : Combien d'utilisateurs utilisent l'abattement pour frais professionnels ?
- **Montants moyens** : Salaire brut moyen, net moyen, coût moyen par CCN
- **Heures et cachets** : Patterns d'utilisation (nombre moyen de cachets, heures par simulation)
- **Périodes** : Analyse temporelle des simulations (jours, semaines, mois)

### Exemples de requêtes PostHog

**Salaire brut moyen par CCN** :
```sql
SELECT 
  ccn_nom,
  AVG(resultat_brut) as brut_moyen,
  COUNT(*) as nb_simulations
FROM events
WHERE event = 'simulateur_calculation'
GROUP BY ccn_nom
ORDER BY nb_simulations DESC
```

**Répartition Artiste vs Technicien** :
```sql
SELECT 
  categorie,
  COUNT(*) as total,
  AVG(resultat_brut) as brut_moyen
FROM events
WHERE event = 'simulateur_calculation'
GROUP BY categorie
```

**Taux d'utilisation de l'abattement** :
```sql
SELECT 
  abattement_active,
  COUNT(*) as total,
  (COUNT(*) * 100.0 / SUM(COUNT(*)) OVER ()) as pourcentage
FROM events
WHERE event = 'simulateur_calculation'
  AND categorie = 'artiste'
GROUP BY abattement_active
```

### Idées d'améliorations futures
- Tracker les exports PDF (si fonctionnalité ajoutée)
- Ajouter le temps passé sur le simulateur
- Tracker les erreurs de validation
- Capturer le device type (mobile/desktop)
- Ajouter des événements pour les modifications de paramètres sans calcul

## Notes techniques

- ✅ Le simulateur est maintenant actif dans la sidebar
- ✅ Les événements PostHog sont trackés avec **toutes les données de simulation**
- ✅ Compatible avec les surveys PostHog
- ✅ Aucune dépendance externe supplémentaire requise
- ✅ Fonctionne en mode production et développement
- ✅ **Données enrichies** : CCN, catégorie, statut, abattement, cachets, heures, dates, montants et résultats complets

## Données capturées (résumé)
| Catégorie | Données |
|-----------|---------|
| **CCN** | ID et nom complet de la convention |
| **Profil** | Catégorie (artiste/technicien), statut (cadre/non-cadre) |
| **Abattement** | Activation et type de profession |
| **Volumes** | Cachets, heures, dates de travail, nombre de jours |
| **Calcul** | Montant saisi, type de calcul (brut/net/cost) |
| **Résultats** | Brut, Net avant PAS, Coût Total Employeur |
| **Contexte** | Plafond URSSAF, timestamp |

## Date de mise en place
- **Première version** : 15 octobre 2025 (tracking basique)
- **Version enrichie** : 16 octobre 2025 (toutes les données)