Flux de travail des enseignants d’instruments avec l’autodétection PostHog et des événements personnalisés

KaushalSaathi est une plateforme éducative axée sur l’IA destinée aux enseignants. Elle permet de rédiger des plans de cours, de guider un mode d’enseignement en plusieurs étapes, de créer des emplois du temps et d’organiser des conversations de coaching. Comme une grande partie de la valeur du produit provient d’une génération asynchrone plutôt que de simples navigations entre pages, la stratégie d’analyse devait considérer les tâches terminées comme des indicateurs de premier ordre — et non seulement les clics et les changements de parcours.

Déployer de nouvelles fonctionnalités sans observer l’utilisation réelle est un piège courant. L’ajout d’écrans supplémentaires ne garantit pas automatiquement de meilleurs résultats. Avant d’ajouter une nouvelle capacité, une équipe a besoin de preuves sur ce que les enseignants utilisent déjà, où ils rencontrent des difficultés et quels outils ils n’ouvrent jamais. L’observabilité du comportement transforme les choix de produit en décisions fondées sur les données réelles d’utilisation. C’est précisément ce problème que PostHog a été conçu pour résoudre : comment les enseignants utilisent-ils réellement le produit déjà existant ?

L’autocapture en tant que référence gratuite

L’autocapture couvre les activités au niveau du DOM sans nécessiter de configuration personnalisée : clics, $pageview, $pageleave ainsi que les limites des sessions. En intégrant ce fournisseur inconditionnellement et en considérant l’absence de clé API comme un mécanisme d’arrêt, le développement local et les versions créées par les contributeurs échappent à toute nécessité de configuration de compte ou à l’utilisation de branches if (enabled) disséminées dans le code :

const POSTHOG_KEY = import.meta.env.VITE_POSTHOG_KEY ?? "phc_disabled_no_key_set";
const ENABLED = POSTHOG_KEY !== "phc_disabled_no_key_set";
<PostHogProvider
apiKey={POSTHOG_KEY}
options={{
api_host: POSTHOG_HOST,
autocapture: ENABLED,
capture_pageview: ENABLED,
session_recording: { maskAllInputs: true },
loaded: (ph) => { if (!ENABLED) ph.opt_out_capturing(); },
}}

L’autocapture indique où quelqu’un a navigué. Elle ne précise pas ce qu’il a terminé. Un gestionnaire de clics DOM ne perçoit jamais l’achèvement d’une tâche asynchrone — que ce soit la génération d’un plan de cours, la fin d’une période en mode enseignement ou l’export réussi d’un PDF. Aucune de ces actions ne génère un clic DOM que l’on puisse intercepter, c’est pourquoi l’autocapture ne peut pas les détecter par conception. C’est précisément ce manque qui justifie l’existence d’une couche supplémentaire.

Événements personnalisés devenus indicateurs

Des résultats significatifs sont émis sous forme d’événements personnalisés à travers un wrapper léger à trois fonctions. Chaque appel vérifie posthog.__loaded, de sorte que le reste de l’application n’a jamais besoin de vérifier si les fonctionnalités d’analyse sont actives ni de se soucier du fait que la capture est en cours :

export function captureEvent(name: string, props?: Record<string, unknown>) {
if (!posthog.__loaded) return;
posthog.capture(name, props);
}

Deux conventions permettent à ces événements de rester utiles pour les requêtes ultérieures.

Émettre l’événement en cas de succès, et non lors de la tentative. La capture s’exécute sur le chemin asynchrone de succès, et non à l’intérieur du gestionnaire de bouton, ce qui permet aux graphiques d’afficher les tâches achevées :

const plan = await generateLessonPlan(payload); // resolves only on success
captureEvent("lesson_plan_generated", {
grade: plan.grade, sector: plan.sector, language: plan.language,
});

Attacher des propriétés qui serviront de dimensions de décomposition. Des champs tels que grade, language, sector et periodNumber sont transmis avec l’événement au moment de son émission. Dans PostHog, ils deviennent des filtres et des critères de décomposition sans nécessiter une nouvelle étape d’instrumentation — un seul événement peut répondre aux questions « par niveau », « par langue » ou « par secteur ».

L’aide-mémoire essentiel est identifyUser, qui doit être exécuté une fois depuis l’hook d’authentification après un succès de connexion. Cette appelation lie l’identifiant anonyme temporaire au compte authentifié et ajoute des champs relatifs aux rôles, ce qui signifie que les captures et enregistrements ultérieurs héritent de la même attribution :

posthog.identify(user.id,
{ role: user.role, grade: user.grade, school: user.school });
// on logout: posthog.reset() ← must run before the redirect, or events leak to the next id

L’ordre des appels lors de la déconnexion est important. Rediriger avant l’appel à reset() sur un appareil partagé peut faire en sorte que la session suivante reste marquée par l’identité précédente. Réinitialisez d’abord, puis naviguez.

Chaque événement fournit ensuite des informations stockées. La méthode habituelle consiste à compter les événements, en les classant par nom de personne :

• lesson_plan_generated sur toute la période, regroupé par heure, produit une série temporelle indiquant quand, ainsi qu’un tableau détaillé classé montrant qui. Cette vue unique met en évidence les utilisateurs avancés, les inscriptions inactives et la concentration de l’utilisation. La limite par ligne par défaut est de 25 ; augmentez-la à 50 lorsque la partie « longue queue » est importante.
• chat_message_sent limité à hier et regroupé par heure réutilise le même événement mais sur une période plus courte — par exemple, un pic l’après-midi vers 15:00 lié à un seul enseignant.

Même définition d’événement, plage de dates et ventilation différentes. Une nouvelle question devient une nouvelle vue enregistrée, pas du nouveau code d’application.

Répétition de session pour comprendre le « pourquoi »

Les comptages expliquent ce que et à quelle fréquence, mais pas pourquoi. L’enregistrement reste activé par défaut avec maskAllInputs: true, car les enseignants saisissent des informations personnelles sensibles concernant les élèves et les écoles. Les clics, la navigation, le niveau de défilement ainsi que les hésitations restent visibles ; les valeurs saisies sont masquées au moment de l’enregistrement.

Lorsque la réexécution est rentable :

• Localisation des fuites dans le processus. Lorsque lesson_plan_generated est déclenché mais que pdf_exported ne l’est pas pour un groupe, les comptages signalent la fuite et la réexécution montre l’étape d’export précise où les utilisateurs abandonnent.
• Faillites silencieuses en plusieurs étapes. Le mode d’enseignement peut échouer discrètement ; les utilisateurs s’arrêtent simplement. La réexécution permet de distinguer un état d’interface défectueux d’une étiquette confuse ou d’un temps de génération trop long qui provoque un timeout.

Chronologies d’activité par utilisateur

Lorsque l’identification lie les captures et les relectures à un compte, l’écran personnel de PostHog affiche une chronologie pour cet éducateur : quels événements se sont produits, quelles fonctionnalités ont été utilisées, quelles sessions ont été enregistrées. Les applications pratiques incluent la vérification qu’une nouvelle entrée registration_completed est suivie d’une première entrée lesson_plan_generated (pour évaluer l’état d’intégration), l’ouverture de la chronologie d’un utilisateur intensif avant de concevoir des solutions adaptées à son parcours, ou la reconstitution d’un bug signalé à partir de la session exacte plutôt que de se fier à la mémoire.

Assembler les différentes couches

L’auto-détection fournit un signal de référence sans coût supplémentaire. Les événements et métriques personnalisés transforment les résultats des fonctionnalités en séries temporelles classées par propriété. La répétition des sessions fournit des détails causaux sur les formes visibles dans les graphiques. Les chronologies individuelles permettent de passer du niveau global à celui d’un seul formateur. Ensemble, ces éléments suffisent pour déterminer ce qu’il convient de développer à partir du comportement observé, plutôt que sur la base d’hypothèses concernant la manière dont le produit « devrait » être utilisé.