instrument-integration

Par posthog · skills

Ajoutez l'intégration du SDK PostHog à votre application. À utiliser lors de la configuration initiale de PostHog ou lors de la revue de PRs nécessitant une initialisation PostHog. Couvre l'installation du SDK, la configuration du provider et la configuration de base pour n'importe quel framework.

npx skills add https://github.com/posthog/skills --skill instrument-integration

Ajouter l'intégration du SDK PostHog

Utilisez cette skill pour ajouter le SDK PostHog à une application. Utilisez-la lors de la configuration de PostHog pour la première fois ou lors de l'examen de PRs nécessitant l'initialisation de PostHog. Couvre l'installation du SDK, la configuration du provider et la configuration de base. Supporte n'importe quel framework ou langage.

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

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 lockfiles (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb) pour déterminer le gestionnaire de paquets.
  • Vérifiez s'il existe une configuration PostHog existante. Si PostHog est déjà installé et initialisé, ne modifiez pas son code. Informez l'utilisateur et passez à la vérification.

ÉTAPE 2 : Recherchez l'intégration. 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 provider et les patterns de configuration. Lisez-le maintenant. 2.2. Si aucune référence ne correspond, revenez à vos connaissances générales et effectuez une recherche sur le web. Utilisez posthog.com/docs comme source de recherche principale.

ÉTAPE 3 : Installez le SDK PostHog.

  • 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 paquets.
  • Installez toujours les paquets en tant que tâche de fond. Ne attendez pas la fin ; poursuivez immédiatement avec les autres travaux après le démarrage de l'installation.

ÉTAPE 4 : Initialisez PostHog.

  • Suivez la référence du framework pour déterminer où et comment 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).
  • Configurez le composant wrapper/provider PostHog si le framework l'exige.

ÉTAPE 5 : Identifiez les utilisateurs.

  • Ajoutez les appels PostHog identify() côté client lors des événements de connexion et d'inscription.
  • Si le frontend et le backend existent tous deux, transmettez la session côté client et l'ID distinct en utilisant les headers X-POSTHOG-DISTINCT-ID et X-POSTHOG-SESSION-ID au code côté serveur.

ÉTAPE 6 : Configurez les variables d'environnement.

  • Vérifiez si le projet a déjà des variables d'environnement PostHog configurées (par ex. dans .env, .env.local ou des fichiers env spécifiques au framework). Si des valeurs valides existent déjà, ignorez cette étape.
  • Si la clé API PostHog est manquante, utilisez le tool projects-get du serveur MCP PostHog pour récupérer l'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 non authentifié, demandez à l'utilisateur sa clé API PostHog à la place.
  • Pour l'URL de l'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é (par ex. .env.local pour Next.js, .env pour les autres) en utilisant la convention de nommage du framework.
  • Référencez ces variables d'environnement dans le code au lieu de les coder en dur.

ÉTAPE 7 : Vérifiez et nettoyez.

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

Fichiers de référence

  • references/EXAMPLE-next-app-router.md - code du projet exemple next-app-router
  • references/EXAMPLE-next-pages-router.md - code du projet exemple next-pages-router
  • references/EXAMPLE-react-react-router-6.md - code du projet exemple react-react-router-6
  • references/EXAMPLE-react-react-router-7-framework.md - code du projet exemple react-react-router-7-framework
  • references/EXAMPLE-react-react-router-7-data.md - code du projet exemple react-react-router-7-data
  • references/EXAMPLE-react-react-router-7-declarative.md - code du projet exemple react-react-router-7-declarative
  • references/EXAMPLE-react-vite.md - code du projet exemple react-vite
  • references/EXAMPLE-nuxt-3-6.md - code du projet exemple nuxt-3-6
  • references/EXAMPLE-nuxt-4.md - code du projet exemple nuxt-4
  • references/EXAMPLE-vue-3.md - code du projet exemple vue-3
  • references/EXAMPLE-react-tanstack-router-file-based.md - code du projet exemple react-tanstack-router-file-based
  • references/EXAMPLE-react-tanstack-router-code-based.md - code du projet exemple react-tanstack-router-code-based
  • references/EXAMPLE-tanstack-start.md - code du projet exemple tanstack-start
  • references/EXAMPLE-sveltekit.md - code du projet exemple sveltekit
  • references/EXAMPLE-astro-static.md - code du projet exemple astro-static
  • references/EXAMPLE-astro-view-transitions.md - code du projet exemple astro-view-transitions
  • references/EXAMPLE-astro-ssr.md - code du projet exemple astro-ssr
  • references/EXAMPLE-astro-hybrid.md - code du projet exemple astro-hybrid
  • references/EXAMPLE-angular.md - code du projet exemple angular
  • references/EXAMPLE-javascript-node.md - code du projet exemple javascript-node
  • references/EXAMPLE-javascript-web.md - code du projet exemple javascript-web
  • references/EXAMPLE-django.md - code du projet exemple django
  • references/EXAMPLE-flask.md - code du projet exemple flask
  • references/EXAMPLE-fastapi.md - code du projet exemple fastapi
  • references/EXAMPLE-python.md - code du projet exemple python
  • references/EXAMPLE-laravel.md - code du projet exemple laravel
  • references/EXAMPLE-ruby-on-rails.md - code du projet exemple ruby-on-rails
  • references/EXAMPLE-ruby.md - code du projet exemple ruby
  • references/EXAMPLE-android.md - code du projet exemple android
  • references/EXAMPLE-swift.md - code du projet exemple swift
  • references/EXAMPLE-react-native.md - code du projet exemple react-native
  • references/EXAMPLE-expo.md - code du projet exemple expo
  • references/next-js.md - Next.js - docs
  • references/react.md - React - 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/js.md - JavaScript web - docs
  • references/posthog-js.md - PostHog JavaScript web SDK
  • references/node.md - Node.js - docs
  • references/posthog-node.md - PostHog Node.js SDK
  • 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 patterns d'installation, d'initialisation et d'utilisation spécifiques au SDK. Trouvez celle qui correspond à la stack 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 à côté des intégrations existantes. Ne remplacez ou ne restructurez pas le code existant.
  • Correspondance avec l'exemple : Votre implémentation doit suivre les patterns du projet exemple aussi fidèlement que possible.
  • Contrat analytics : Traitez les noms d'événements, les noms de propriétés et les clés de feature flags comme faisant partie d'un contrat analytics. Réutilisez les noms et patterns existants trouvés dans le projet. Lorsque vous en introduisez de nouveaux, rendez-les clairs, descriptifs et cohérents avec les conventions existantes.

Skills similaires

performance-report
anthropics / knowledge-work-plugins

Générer un rapport marketing complet avec métriques, tendances et recommandations d'optimisation.

12 185
posthog-pls-big-fish
posthog / skills

Qualifier et contacter des leads grands comptes product-led via recherche et analyse d'usage.

37
business-launcher
elophanto / elophanto

Lancer une entreprise de A à Z, de la validation d'idée au déploiement autonome.

72
metrics-review
anthropics / knowledge-work-plugins

Analyser les métriques produit, identifier les tendances et générer des insights actionnables.

12 185
gtm-ai-gtm
github / awesome-copilot

Vendre des agents IA autonomes en entreprise en levant les objections organisationnelles réelles.

33 044