Ajouter des événements d'analyse produit PostHog

Utilisez cette skill pour ajouter des événements d'analyse produit (appels capture) qui suivi les actions utilisateur significatives dans du code nouveau ou modifié. Utilisez-la après la mise en œuvre de fonctionnalités ou l'examen de PRs pour garantir que les comportements clés des utilisateurs sont capturés. Si PostHog n'est pas encore installé, cette skill couvre également la configuration initiale du SDK. Supporte n'importe quel framework ou langage.

Frameworks supportés : Next.js, React Router, Nuxt, Vue, TanStack Start, SvelteKit, Astro, Angular, Django, Flask, FastAPI, Laravel, Ruby on Rails, Android, iOS, React Native, Expo, et plus.

Instructions

Suivez ces étapes DANS L'ORDRE :

ÉTAPE 1 : Analyser la base de code et détecter la plateforme.

• Recherchez les fichiers de dépendances (package.json, requirements.txt, Gemfile, composer.json, go.mod, etc.) pour déterminer le framework et le langage.
• Recherchez les fichiers de verrouillage (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb) pour déterminer le gestionnaire de packages.
• Vérifiez la configuration PostHog existante. Si PostHog est déjà installé et initialisé, passez à l'ÉTAPE 5.

ÉTAPE 2 : Rechercher l'intégration. (Ignorer si PostHog est déjà configuré.) 2.1. Trouvez le fichier de référence ci-dessous qui correspond au framework détecté — c'est la source de vérité pour l'initialisation du SDK, la configuration du fournisseur et les modèles de capture d'événements. Lisez-le maintenant. 2.2. Si aucune référence ne correspond, revoyez à vos connaissances générales et recherche web. Utilisez posthog.com/docs comme source de recherche principale.

ÉTAPE 3 : Installer le SDK PostHog. (Ignorer si PostHog est déjà configuré.)

• Ajoutez le package du SDK PostHog pour la plateforme détectée. N'éditez pas manuellement package.json — utilisez la commande d'installation du gestionnaire de packages.
• Installez toujours les packages comme une tâche de fond. N'attendez pas l'accomplissement ; continuez avec d'autres travaux immédiatement après le démarrage de l'installation.

ÉTAPE 4 : Initialiser PostHog. (Ignorer si PostHog est déjà configuré.)

• Suivez la référence du framework pour le lieu et la façon d'initialiser. Cela varie considérablement selon le framework (par exemple, instrumentation-client.ts pour Next.js 15.3+, AppConfig.ready() pour Django, create_app() pour Flask).

ÉTAPE 5 : Planifier le suivi des événements.

• À partir de la liste des fichiers du projet, sélectionnez entre 10 et 15 fichiers qui pourraient avoir une valeur commerciale intéressante pour le suivi des événements, en particulier les événements de conversion et d'attrition.
• Recherchez également les fichiers liés à la connexion qui pourraient être utilisés pour identifier les utilisateurs, ainsi que la gestion des erreurs.
• Trouvez tout code posthog.capture() existant. Notez le format du nom de l'événement. Ne dupliquez pas les événements existants ; complétez-les.
• Suivez les actions uniquement, pas les pageviews (celles-ci peuvent être capturées automatiquement). Des exceptions peuvent être faites pour les événements de type « viewed » au début d'un tunnel de conversion.
• Les événements côté serveur sont OBLIGATOIRES si le projet inclut du code côté serveur instrumentable (routes API, actions serveur, gestionnaires webhook, completion paiement/checkout, endpoints d'authentification).

ÉTAPE 6 : Implémenter la capture d'événements.

• Pour chaque événement planifié, ajoutez des appels posthog.capture() avec des propriétés utiles.
• Si un fichier a déjà du code d'intégration existant pour d'autres outils ou services, ne le remplacez ou supprimez pas. Placez le code PostHog au-dessous.
• N'altérez pas l'architecture fondamentale des fichiers existants. Rendez les ajouts minimaux et ciblés.
• Vous devez lire un fichier immédiatement avant de tenter de l'écrire.

ÉTAPE 7 : Identifier les utilisateurs.

• Ajoutez des appels PostHog identify() côté client lors des événements de connexion et d'inscription. Utilisez le contenu des formulaires de connexion et d'inscription pour identifier les utilisateurs à la soumission.
• Si à la fois le frontend et le backend existent, transmettez la session côté client et l'ID distinct en utilisant les en-têtes X-POSTHOG-DISTINCT-ID et X-POSTHOG-SESSION-ID au code côté serveur. Côté serveur, assurez-vous que les événements ont un ID distinct correspondant.

ÉTAPE 8 : Ajouter le suivi des erreurs.

• Ajoutez la capture d'exceptions PostHog pour le suivi des erreurs aux fichiers pertinents, en particulier autour des flux utilisateur critiques et des limites API.

ÉTAPE 9 : Configurer les variables d'environnement.

• Vérifiez si le projet a déjà les variables d'environnement PostHog configurées (par exemple dans .env, .env.local, ou les fichiers env spécifiques au framework). Si des valeurs valides existent déjà, ignorez cette étape.
• Si la clé API PostHog manque, utilisez l'outil projects-get du serveur MCP PostHog pour récupérer le api_token du projet. Si plusieurs projets sont retournés, demandez à l'utilisateur quel projet utiliser. Si le serveur MCP n'est pas connecté ou pas authentifié, demandez à l'utilisateur sa clé API PostHog à la place.
• Pour l'URL d'hôte PostHog, utilisez https://us.i.posthog.com pour US Cloud ou https://eu.i.posthog.com pour EU Cloud.
• Écrivez ces valeurs dans le fichier env approprié en utilisant la convention de dénomination du framework.
• Référencez ces variables d'environnement dans le code au lieu de les coder en dur.

ÉTAPE 10 : Vérifier et nettoyer.

• Vérifiez le projet pour les erreurs. Recherchez la vérification de type ou les scripts de build dans package.json.
• Assurez-vous que tous les composants créés ont réellement été utilisés.
• Exécutez les scripts linter ou prettier trouvés dans package.json.

Fichiers de référence

• references/EXAMPLE-next-app-router.md - code de projet exemple next-app-router
• references/EXAMPLE-next-pages-router.md - code de projet exemple next-pages-router
• references/EXAMPLE-react-react-router-6.md - code de projet exemple react-react-router-6
• references/EXAMPLE-react-react-router-7-framework.md - code de projet exemple react-react-router-7-framework
• references/EXAMPLE-react-react-router-7-data.md - code de projet exemple react-react-router-7-data
• references/EXAMPLE-react-react-router-7-declarative.md - code de projet exemple react-react-router-7-declarative
• references/EXAMPLE-nuxt-3-6.md - code de projet exemple nuxt-3-6
• references/EXAMPLE-nuxt-4.md - code de projet exemple nuxt-4
• references/EXAMPLE-vue-3.md - code de projet exemple vue-3
• references/EXAMPLE-react-tanstack-router-file-based.md - code de projet exemple react-tanstack-router-file-based
• references/EXAMPLE-react-tanstack-router-code-based.md - code de projet exemple react-tanstack-router-code-based
• references/EXAMPLE-tanstack-start.md - code de projet exemple tanstack-start
• references/EXAMPLE-sveltekit.md - code de projet exemple sveltekit
• references/EXAMPLE-astro-static.md - code de projet exemple astro-static
• references/EXAMPLE-astro-view-transitions.md - code de projet exemple astro-view-transitions
• references/EXAMPLE-astro-ssr.md - code de projet exemple astro-ssr
• references/EXAMPLE-astro-hybrid.md - code de projet exemple astro-hybrid
• references/EXAMPLE-angular.md - code de projet exemple angular
• references/EXAMPLE-django.md - code de projet exemple django
• references/EXAMPLE-flask.md - code de projet exemple flask
• references/EXAMPLE-fastapi.md - code de projet exemple fastapi
• references/EXAMPLE-python.md - code de projet exemple python
• references/EXAMPLE-laravel.md - code de projet exemple laravel
• references/EXAMPLE-ruby-on-rails.md - code de projet exemple ruby-on-rails
• references/EXAMPLE-ruby.md - code de projet exemple ruby
• references/EXAMPLE-android.md - code de projet exemple android
• references/EXAMPLE-swift.md - code de projet exemple swift
• references/EXAMPLE-react-native.md - code de projet exemple react-native
• references/EXAMPLE-expo.md - code de projet exemple expo
• references/next-js.md - Next.js - docs
• references/react-router-v6.md - React router v6 - docs
• references/react-router-v7-framework-mode.md - React router v7 mode framework (remix v3) - docs
• references/react-router-v7-data-mode.md - React router v7 mode données - docs
• references/react-router-v7-declarative-mode.md - React router v7 mode déclaratif - docs
• references/nuxt-js-3-6.md - Nuxt.js (v3.0 à v3.6) - docs
• references/nuxt-js.md - Nuxt.js - docs
• references/vue-js.md - Vue.js - docs
• references/tanstack-start.md - Tanstack start - docs
• references/svelte.md - Svelte - docs
• references/astro.md - Astro - docs
• references/angular.md - Angular - docs
• references/django.md - Django - docs
• references/flask.md - Flask - docs
• references/python.md - Python - docs
• references/posthog-python.md - PostHog python SDK
• references/laravel.md - Laravel - docs
• references/ruby-on-rails.md - Ruby on rails - docs
• references/ruby.md - Ruby - docs
• references/android.md - Android - docs
• references/ios.md - Ios - docs
• references/react-native.md - React native - docs
• references/identify-users.md - Identify users - docs

Chaque référence de framework contient des modèles spécifiques à l'SDK pour l'installation, l'initialisation et l'utilisation. Trouvez celui qui correspond à la pile de l'utilisateur.

Principes clés

• Variables d'environnement : Utilisez toujours les variables d'environnement pour les clés PostHog. Ne les codez jamais en dur.
• Changements minimaux : Ajoutez le code PostHog aux côtés des intégrations existantes. Ne remplacez ou restructurez pas le code existant.
• Correspondre aux docs : Suivez exactement les modèles d'initialisation et de capture de la référence du framework.