Installer PostHog dans une base de code

Utilise cette skill quand tu peux lire et modifier le code de l'utilisateur. Si tu n'as pas accès à son code, comme c'est souvent le cas dans ChatGPT sur le web ou Claude sur le web, utilise installing-posthog-from-chat.

La documentation PostHog est la source de référence pour la configuration de chaque SDK. Les options d'init, les emplacements de fichiers et les paramètres recommandés changent entre les versions du SDK, donc lis la page de documentation du framework avant d'écrire du code, et suis-la plutôt que ce dont tu te souviens.

1. Trouve le framework et lis sa documentation

Détecte le framework à partir des fichiers manifest (package.json, pyproject.toml, requirements.txt, Gemfile, composer.json, go.mod, etc.) et des points d'entrée de l'app. Une app web avec son propre backend a généralement besoin d'un SDK client et d'un SDK serveur, donc lis les deux pages.

Pour un framework qui n'est pas listé, appelle docs-search avec le nom du framework.

2. Installe le dernier SDK

Ajoute chaque package avec le gestionnaire de paquets du projet et sans version, par exemple npm install posthog-js, pnpm add posthog-node, uv add posthog ou bundle add posthog-ruby. Cela résout la version la plus récente. Ne saisis pas de version dans le manifest de mémoire, car cela épinglerait une ancienne version.

Dans un monorepo, installe dans le package qui exécute l'app, pas dans la racine du workspace.

3. Récupère le token et l'hôte

Appelle project-get sans ID. Utilise api_token comme token du projet et api_host comme option hôte du SDK.

• Lis les deux depuis les variables d'environnement dans le code, en utilisant les noms que la page de documentation utilise (par exemple NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN et NEXT_PUBLIC_POSTHOG_HOST).
• Écris les vraies valeurs dans le fichier env que le framework charge, comme .env.local ou .env. Si le projet a un fichier env exemple, ajoute les noms de variables là avec des valeurs vides.
• Ne code jamais en dur le token ou l'hôte dans les fichiers source, et ne les utilise jamais comme valeurs par défaut de secours dans le code.

4. Initialise comme la documentation le montre

• Initialise le SDK une seule fois, à l'endroit que la page de documentation nomme. N'ajoute pas une deuxième initialisation ailleurs.
• Pour posthog-js, définis defaults à la date que la page de documentation montre. Cela sélectionne l'ensemble le plus récent de paramètres recommandés, donc ne prends pas une date de mémoire.
• Pour un SDK backend dans un serveur à longue durée de vie, crée un client pour le processus, réutilise-le, et arrête-le quand le processus se termine. Ne crée pas un client par requête.
• Dans les handlers serverless ou edge (par exemple les route handlers Next.js sur Vercel, ou AWS Lambda), le runtime peut se figer dès que la réponse est envoyée, donc les événements en file d'attente sont perdus. Vide avant que le handler retourne : await flush() sur un client réutilisé, ou utilise le waitUntil de la plateforme, comme la page de documentation le décrit.
• Pour une app server-rendered (Django, Rails, Laravel et similaires), ajoute le SDK serveur ainsi que le snippet de navigateur.

5. Identifie les utilisateurs

Si l'app a une connexion, appelle identify après la connexion avec un ID utilisateur stable du système d'authentification, comme l'ID de base de données, pas une adresse email ou un nom d'affichage. Appelle reset() à la déconnexion. Envoie les événements côté serveur avec le même distinct ID, pour que les événements client et serveur se retrouvent sur la même personne.

6. Vérifie

Exécute la construction, la vérification des types ou les tests du projet, et corrige tout ce que ton changement a cassé. Si tu peux exécuter l'app, charge une page et vérifie que les événements arrivent avec read-data-schema ou execute-sql. Dis à l'utilisateur quelles variables d'environnement ajouter dans son fournisseur d'hébergement avant qu'il ne déploie.