instrument-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Add PostHog SDK integration

集成PostHog SDK

Use this skill to add the PostHog SDK to an application. Use it when setting up PostHog for the first time, or reviewing PRs that need PostHog initialization. Covers SDK installation, provider setup, and basic configuration. Supports any framework or language.

Supported frameworks: 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, and vanilla JavaScript.

本技能用于为应用添加PostHog SDK。适用于首次搭建PostHog环境，或审核需要初始化PostHog的PR场景。内容涵盖SDK安装、提供者配置及基础设置，支持任意框架或语言。

支持的框架：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 以及原生JavaScript。

Instructions

操作步骤

Follow these steps IN ORDER:

STEP 1: Analyze the codebase and detect the platform.

Look for dependency files (package.json, requirements.txt, Gemfile, composer.json, go.mod, etc.) to determine the framework and language.
Look for lockfiles (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb) to determine the package manager.
Check for existing PostHog setup. If PostHog is already installed and initialized, do not modify its code. Inform the user and skip to verification.

STEP 2: Research integration. 2.1. Find the reference file below that matches the detected framework — it is the source of truth for SDK initialization, provider setup, and configuration patterns. Read it now. 2.2. If no reference matches, fall back to your general knowledge and web search. Use posthog.com/docs as the primary search source.

STEP 3: Install the PostHog SDK.

Add the PostHog SDK package for the detected platform. Do not manually edit package.json — use the package manager's install command.
Always install packages as a background task. Don't await completion; proceed with other work immediately after starting the installation.

STEP 4: Initialize PostHog.

Follow the framework reference for where and how to initialize. This varies significantly by framework (e.g., instrumentation-client.ts for Next.js 15.3+, AppConfig.ready() for Django, create_app() for Flask).
Set up the PostHog provider/wrapper component if the framework requires one.

STEP 5: Identify users.

Add PostHog
```
identify()
```
calls on the client side during login and signup events.
If both frontend and backend exist, pass the client-side session and distinct ID using
```
X-POSTHOG-DISTINCT-ID
```
and
```
X-POSTHOG-SESSION-ID
```
headers to the server-side code.

STEP 6: Set up environment variables.

Check if the project already has PostHog environment variables configured (e.g. in
```
.env
```
,
```
.env.local
```
, or framework-specific env files). If valid values already exist, skip this step.
If the PostHog API key is missing, use the PostHog MCP server's
```
projects-get
```
tool to retrieve the project's
```
api_token
```
. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project API key instead.
For the PostHog host URL, use
```
https://us.i.posthog.com
```
for US Cloud or
```
https://eu.i.posthog.com
```
for EU Cloud.
Write these values to the appropriate env file (e.g.
```
.env.local
```
for Next.js,
```
.env
```
for others) using the framework's naming convention.
Reference these environment variables in code instead of hardcoding them.

STEP 7: Verify and clean up.

Check the project for errors. Look for type checking or build scripts in package.json.
Ensure any components created were actually used.
Run any linter or prettier-like scripts found in the package.json.

请按顺序执行以下步骤：

STEP 1: 分析代码库并检测平台。

查找依赖文件（package.json、requirements.txt、Gemfile、composer.json、go.mod等）以确定框架和语言。
查找锁定文件（pnpm-lock.yaml、package-lock.json、yarn.lock、bun.lockb）以确定包管理器。
检查是否已存在PostHog配置。若PostHog已安装并初始化，则无需修改代码，告知用户并直接跳至验证步骤。

STEP 2: 调研集成方案。 2.1. 找到与检测到的框架匹配的下方参考文件——它是SDK初始化、提供者配置及设置模式的权威来源，请立即阅读。 2.2. 若没有匹配的参考文件，则依靠你的通用知识和网络搜索。以posthog.com/docs作为主要搜索来源。

STEP 3: 安装PostHog SDK。

为检测到的平台添加PostHog SDK包。请勿手动编辑package.json——使用包管理器的安装命令。
始终将包安装作为后台任务执行。无需等待安装完成，启动安装后立即开展其他工作。

STEP 4: 初始化PostHog。

遵循框架参考文档的指引，确定初始化的位置和方式。不同框架的差异较大（例如Next.js 15.3+使用instrumentation-client.ts，Django使用AppConfig.ready()，Flask使用create_app()）。
若框架要求，设置PostHog提供者/包装组件。

STEP 5: 用户身份识别。

在客户端的登录和注册事件中添加PostHog
```
identify()
```
调用。
若同时存在前端和后端，通过
```
X-POSTHOG-DISTINCT-ID
```
和
```
X-POSTHOG-SESSION-ID
```
请求头，将客户端会话和唯一ID传递给服务端代码。

STEP 6: 设置环境变量。

检查项目是否已配置PostHog环境变量（例如在.env、.env.local或框架特定的环境文件中）。若已存在有效值，则跳过此步骤。
若缺少PostHog API密钥，使用PostHog MCP服务器的
```
projects-get
```
工具获取项目的
```
api_token
```
。若返回多个项目，请询问用户使用哪个项目。若未连接MCP服务器或未完成认证，则请用户提供其PostHog项目API密钥。
PostHog主机URL：美国云环境使用
```
https://us.i.posthog.com
```
，欧盟云环境使用
```
https://eu.i.posthog.com
```
。
按照框架的命名规范，将这些值写入对应的环境文件（例如Next.js使用.env.local，其他框架使用.env）。
在代码中引用这些环境变量，而非硬编码。

STEP 7: 验证与清理。

检查项目是否存在错误。查找package.json中的类型检查或构建脚本。
确保创建的所有组件均已实际使用。
运行package.json中找到的任何代码检查或格式化脚本（如linter、prettier）。

Reference files

参考文件

```
references/EXAMPLE-next-app-router.md
```
- next-app-router example project code
```
references/EXAMPLE-next-pages-router.md
```
- next-pages-router example project code
```
references/EXAMPLE-react-react-router-6.md
```
- react-react-router-6 example project code
```
references/EXAMPLE-react-react-router-7-framework.md
```
- react-react-router-7-framework example project code
```
references/EXAMPLE-react-react-router-7-data.md
```
- react-react-router-7-data example project code
```
references/EXAMPLE-react-react-router-7-declarative.md
```
- react-react-router-7-declarative example project code
```
references/EXAMPLE-react-vite.md
```
- react-vite example project code
```
references/EXAMPLE-nuxt-3-6.md
```
- nuxt-3-6 example project code
```
references/EXAMPLE-nuxt-4.md
```
- nuxt-4 example project code
```
references/EXAMPLE-vue-3.md
```
- vue-3 example project code
```
references/EXAMPLE-react-tanstack-router-file-based.md
```
- react-tanstack-router-file-based example project code
```
references/EXAMPLE-react-tanstack-router-code-based.md
```
- react-tanstack-router-code-based example project code
```
references/EXAMPLE-tanstack-start.md
```
- tanstack-start example project code
```
references/EXAMPLE-sveltekit.md
```
- sveltekit example project code
```
references/EXAMPLE-astro-static.md
```
- astro-static example project code
```
references/EXAMPLE-astro-view-transitions.md
```
- astro-view-transitions example project code
```
references/EXAMPLE-astro-ssr.md
```
- astro-ssr example project code
```
references/EXAMPLE-astro-hybrid.md
```
- astro-hybrid example project code
```
references/EXAMPLE-angular.md
```
- angular example project code
```
references/EXAMPLE-javascript-node.md
```
- javascript-node example project code
```
references/EXAMPLE-javascript-web.md
```
- javascript-web example project code
```
references/EXAMPLE-django.md
```
- django example project code
```
references/EXAMPLE-flask.md
```
- flask example project code
```
references/EXAMPLE-fastapi.md
```
- fastapi example project code
```
references/EXAMPLE-python.md
```
- python example project code
```
references/EXAMPLE-laravel.md
```
- laravel example project code
```
references/EXAMPLE-ruby-on-rails.md
```
- ruby-on-rails example project code
```
references/EXAMPLE-ruby.md
```
- ruby example project code
```
references/EXAMPLE-android.md
```
- android example project code
```
references/EXAMPLE-swift.md
```
- swift example project code
```
references/EXAMPLE-react-native.md
```
- react-native example project code
```
references/EXAMPLE-expo.md
```
- expo example project code
```
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

Each framework reference contains SDK-specific installation, initialization, and usage patterns. Find the one matching the user's stack.

```
references/EXAMPLE-next-app-router.md
```
- next-app-router示例项目代码
```
references/EXAMPLE-next-pages-router.md
```
- next-pages-router示例项目代码

references/EXAMPLE-react-react-router-6.md

- react-react-router-6示例项目代码

references/EXAMPLE-react-react-router-7-framework.md

- react-react-router-7-framework示例项目代码

references/EXAMPLE-react-react-router-7-data.md

- react-react-router-7-data示例项目代码

references/EXAMPLE-react-react-router-7-declarative.md

- react-react-router-7-declarative示例项目代码

```
references/EXAMPLE-react-vite.md
```
- react-vite示例项目代码
```
references/EXAMPLE-nuxt-3-6.md
```
- nuxt-3-6示例项目代码
```
references/EXAMPLE-nuxt-4.md
```
- nuxt-4示例项目代码
```
references/EXAMPLE-vue-3.md
```
- vue-3示例项目代码

references/EXAMPLE-react-tanstack-router-file-based.md

- react-tanstack-router-file-based示例项目代码

references/EXAMPLE-react-tanstack-router-code-based.md

- react-tanstack-router-code-based示例项目代码

```
references/EXAMPLE-tanstack-start.md
```
- tanstack-start示例项目代码
```
references/EXAMPLE-sveltekit.md
```
- sveltekit示例项目代码
```
references/EXAMPLE-astro-static.md
```
- astro-static示例项目代码

references/EXAMPLE-astro-view-transitions.md

- astro-view-transitions示例项目代码

```
references/EXAMPLE-astro-ssr.md
```
- astro-ssr示例项目代码
```
references/EXAMPLE-astro-hybrid.md
```
- astro-hybrid示例项目代码
```
references/EXAMPLE-angular.md
```
- angular示例项目代码
```
references/EXAMPLE-javascript-node.md
```
- javascript-node示例项目代码
```
references/EXAMPLE-javascript-web.md
```
- javascript-web示例项目代码
```
references/EXAMPLE-django.md
```
- django示例项目代码
```
references/EXAMPLE-flask.md
```
- flask示例项目代码
```
references/EXAMPLE-fastapi.md
```
- fastapi示例项目代码
```
references/EXAMPLE-python.md
```
- python示例项目代码
```
references/EXAMPLE-laravel.md
```
- laravel示例项目代码
```
references/EXAMPLE-ruby-on-rails.md
```
- ruby-on-rails示例项目代码
```
references/EXAMPLE-ruby.md
```
- ruby示例项目代码
```
references/EXAMPLE-android.md
```
- android示例项目代码
```
references/EXAMPLE-swift.md
```
- swift示例项目代码
```
references/EXAMPLE-react-native.md
```
- react-native示例项目代码
```
references/EXAMPLE-expo.md
```
- expo示例项目代码
```
references/next-js.md
```
- Next.js - 文档
```
references/react.md
```
- React - 文档
```
references/react-router-v6.md
```
- React router v6 - 文档
```
references/react-router-v7-framework-mode.md
```
- React router v7 framework mode (remix v3) - 文档
```
references/react-router-v7-data-mode.md
```
- React router v7 data mode - 文档

references/react-router-v7-declarative-mode.md

- React router v7 declarative mode - 文档

```
references/nuxt-js-3-6.md
```
- Nuxt.js (v3.0 to v3.6) - 文档
```
references/nuxt-js.md
```
- Nuxt.js - 文档
```
references/vue-js.md
```
- Vue.js - 文档
```
references/tanstack-start.md
```
- Tanstack start - 文档
```
references/svelte.md
```
- Svelte - 文档
```
references/astro.md
```
- Astro - 文档
```
references/angular.md
```
- Angular - 文档
```
references/js.md
```
- JavaScript web - 文档
```
references/posthog-js.md
```
- PostHog JavaScript web SDK
```
references/node.md
```
- Node.js - 文档
```
references/posthog-node.md
```
- PostHog Node.js SDK
```
references/django.md
```
- Django - 文档
```
references/flask.md
```
- Flask - 文档
```
references/python.md
```
- Python - 文档
```
references/posthog-python.md
```
- PostHog python SDK
```
references/laravel.md
```
- Laravel - 文档
```
references/ruby-on-rails.md
```
- Ruby on rails - 文档
```
references/ruby.md
```
- Ruby - 文档
```
references/android.md
```
- Android - 文档
```
references/ios.md
```
- Ios - 文档
```
references/react-native.md
```
- React native - 文档
```
references/identify-users.md
```
- Identify users - 文档

每个框架参考文件都包含特定SDK的安装、初始化及使用模式。请找到与用户技术栈匹配的文件。

Key principles

核心原则

Environment variables: Always use environment variables for PostHog keys. Never hardcode them.
Minimal changes: Add PostHog code alongside existing integrations. Don't replace or restructure existing code.
Match the example: Your implementation should follow the example project's patterns as closely as possible.
Analytics contract: Treat event names, property names, and feature flag keys as part of an analytics contract. Reuse existing names and patterns found in the project. When introducing new ones, make them clear, descriptive, and consistent with existing conventions.

环境变量：始终使用环境变量存储PostHog密钥，绝不要硬编码。
最小改动：在现有集成代码旁添加PostHog代码，不要替换或重构现有代码。
匹配示例：你的实现应尽可能贴近示例项目的模式。
分析契约：将事件名称、属性名称和功能标志密钥视为分析契约的一部分。复用项目中已有的名称和模式。引入新名称时，要清晰、描述性强，并与现有约定保持一致。