Ajouter des événements d'analyse de produits PostHog

Utilisez cette compétence pour ajouter des événements d'analyse de produits (appels capture) qui suivi les actions utilisateur significatives dans le code nouveau ou modifié. Utilisez-la après l'implémentation de fonctionnalités ou l'examen de pull requests pour vous assurer que les comportements clés des utilisateurs sont capturés. Si PostHog n'est pas encore installé, cette compétence couvre également la configuration initiale du SDK. Compatible avec 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 : Analysez la base de code et détectez 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 paquets.
• Vérifiez l'existence d'une configuration PostHog. Si PostHog est déjà installé et initialisé, passez directement à l'ÉTAPE 5.

ÉTAPE 2 : Recherchez l'intégration. (Ignorez 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, consultez vos connaissances générales et effectuez une recherche web. Utilisez posthog.com/docs comme source de recherche principale.

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

• Ajoutez le paquet SDK PostHog pour la plateforme détectée. N'éditez pas manuellement package.json — utilisez la commande d'installation du gestionnaire de paquets.
• Installez toujours les paquets en tant que tâche de fond. N'attendez pas l'achèvement ; continuez avec d'autres tâches immédiatement après avoir démarré l'installation.

ÉTAPE 4 : Initialisez PostHog. (Ignorez si PostHog est déjà configuré.)

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

ÉTAPE 5 : Planifiez 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 de churn.
• Recherchez aussi 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 formatage des noms d'événements. Ne dupliquez pas les événements existants ; complétez-les.
• Suivez uniquement les actions, pas les pages vues (celles-ci peuvent être capturées automatiquement). Des exceptions peuvent être faites pour les événements de type « viewed » en haut d'un entonnoir de conversion.
• Les événements côté serveur sont OBLIGATOIRES si le projet contient du code côté serveur instrumentable (routes API, actions serveur, gestionnaires webhook, achèvement du paiement/checkout, points d'accès d'authentification).

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

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

ÉTAPE 7 : Identifiez 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 le frontend et le backend existent tous les deux, 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 : Ajoutez le suivi des erreurs.

• Ajoutez le suivi de capture d'exceptions PostHog aux fichiers pertinents, particulièrement autour des flux utilisateur critiques et des limites API.

ÉTAPE 9 : Configurez les variables d'environnement.

• Si un serveur MCP env-file-tools est connecté, utilisez check_env_keys pour voir quelles clés existent déjà, puis utilisez set_env_values pour créer ou mettre à jour la clé API et l'hôte PostHog.
• Référencez ces variables d'environnement dans le code au lieu de les coder en dur.

ÉTAPE 10 : Vérifiez et nettoyez.

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

Fichiers de référence

• references/EXAMPLE-next-app-router.md - code d'exemple de projet next-app-router
• references/EXAMPLE-next-pages-router.md - code d'exemple de projet next-pages-router
• references/EXAMPLE-react-react-router-6.md - code d'exemple de projet react-react-router-6
• references/EXAMPLE-react-react-router-7-framework.md - code d'exemple de projet react-react-router-7-framework
• references/EXAMPLE-react-react-router-7-data.md - code d'exemple de projet react-react-router-7-data
• references/EXAMPLE-react-react-router-7-declarative.md - code d'exemple de projet react-react-router-7-declarative
• references/EXAMPLE-nuxt-3.6.md - code d'exemple de projet nuxt-3.6
• references/EXAMPLE-nuxt-4.md - code d'exemple de projet nuxt-4
• references/EXAMPLE-vue-3.md - code d'exemple de projet vue-3
• references/EXAMPLE-react-tanstack-router-file-based.md - code d'exemple de projet react-tanstack-router-file-based
• references/EXAMPLE-react-tanstack-router-code-based.md - code d'exemple de projet react-tanstack-router-code-based
• references/EXAMPLE-tanstack-start.md - code d'exemple de projet tanstack-start
• references/EXAMPLE-sveltekit.md - code d'exemple de projet sveltekit
• references/EXAMPLE-astro-static.md - code d'exemple de projet astro-static
• references/EXAMPLE-astro-view-transitions.md - code d'exemple de projet astro-view-transitions
• references/EXAMPLE-astro-ssr.md - code d'exemple de projet astro-ssr
• references/EXAMPLE-astro-hybrid.md - code d'exemple de projet astro-hybrid
• references/EXAMPLE-angular.md - code d'exemple de projet angular
• references/EXAMPLE-django.md - code d'exemple de projet django
• references/EXAMPLE-flask.md - code d'exemple de projet flask
• references/EXAMPLE-fastapi.md - code d'exemple de projet fastapi
• references/EXAMPLE-python.md - code d'exemple de projet python
• references/EXAMPLE-laravel.md - code d'exemple de projet laravel
• references/EXAMPLE-ruby-on-rails.md - code d'exemple de projet ruby-on-rails
• references/EXAMPLE-ruby.md - code d'exemple de projet ruby
• references/EXAMPLE-android.md - code d'exemple de projet android
• references/EXAMPLE-swift.md - code d'exemple de projet swift
• references/EXAMPLE-react-native.md - code d'exemple de projet react-native
• references/EXAMPLE-expo.md - code d'exemple de projet 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 framework mode (remix v3) - docs
• references/react-router-v7-data-mode.md - React router v7 data mode - docs
• references/react-router-v7-declarative-mode.md - React router v7 declarative mode - docs
• references/nuxt-js-3-6.md - Nuxt.js (v3.0 to 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 les modèles d'installation, d'initialisation et d'utilisation spécifiques au SDK. Trouvez celle qui correspond à la pile de l'utilisateur.

Principes clés

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