instrument-product-analytics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Add PostHog product analytics events

添加PostHog产品分析事件

Use this skill to add product analytics events (capture calls) that track meaningful user actions in new or changed code. Use it after implementing features or reviewing PRs to ensure key user behaviors are captured. If PostHog is not yet installed, this skill also covers initial SDK setup. Supports any framework or language.

Supported frameworks: Next.js, React Router, Nuxt, Vue, TanStack Start, SvelteKit, Astro, Angular, Django, Flask, FastAPI, Laravel, Ruby on Rails, Android, iOS, React Native, Expo, and more.

使用此技能在新增或修改的代码中添加产品分析事件（capture调用），以追踪有意义的用户操作。可在实现功能或审核PR后使用，确保捕获关键用户行为。如果尚未安装PostHog，该技能也涵盖SDK的初始设置。支持任意框架或语言。

支持的框架：Next.js、React Router、Nuxt、Vue、TanStack Start、SvelteKit、Astro、Angular、Django、Flask、FastAPI、Laravel、Ruby on Rails、Android、iOS、React Native、Expo等。

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, skip to STEP 5.

STEP 2: Research integration. (Skip if PostHog is already set up.) 2.1. Find the reference file below that matches the detected framework — it is the source of truth for SDK initialization, provider setup, and event capture 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. (Skip if PostHog is already set up.)

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. (Skip if PostHog is already set up.)

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).

STEP 5: Plan event tracking.

From the project's file list, select between 10 and 15 files that might have interesting business value for event tracking, especially conversion and churn events.
Also look for files related to login that could be used for identifying users, along with error handling.
Find any existing
```
posthog.capture()
```
code. Make note of event name formatting. Don't duplicate existing events; supplement them.
Track actions only, not pageviews (those can be captured automatically). Exceptions can be made for "viewed"-type events at the top of a conversion funnel.
Server-side events are REQUIRED if the project includes any instrumentable server-side code (API routes, server actions, webhook handlers, payment/checkout completion, authentication endpoints).

STEP 6: Implement event capture.

For each planned event, add
```
posthog.capture()
```
calls with useful properties.
If a file already has existing integration code for other tools or services, don't overwrite or remove that code. Place PostHog code below it.
Do not alter the fundamental architecture of existing files. Make additions minimal and targeted.
You must read a file immediately before attempting to write it.

STEP 7: Identify users.

Add PostHog
```
identify()
```
calls on the client side during login and signup events. Use the contents of login and signup forms to identify users on submit.
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. On the server side, make sure events have a matching distinct ID.

STEP 8: Add error tracking.

Add PostHog exception capture error tracking to relevant files, particularly around critical user flows and API boundaries.

STEP 9: Set up environment variables.

If an env-file-tools MCP server is connected, use check_env_keys to see which keys already exist, then use set_env_values to create or update the PostHog API key and host.
Reference these environment variables in code instead of hardcoding them.

STEP 10: 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.

请严格按照以下顺序执行：

步骤1：分析代码库并检测平台

查找依赖文件（package.json、requirements.txt、Gemfile、composer.json、go.mod等）以确定框架和语言。
查找锁文件（pnpm-lock.yaml、package-lock.json、yarn.lock、bun.lockb）以确定包管理器。
检查是否已存在PostHog设置。如果PostHog已安装并初始化，跳至步骤5。

步骤2：调研集成方式（若已设置PostHog则跳过） 2.1. 找到与检测到的框架匹配的下方参考文件——该文件是SDK初始化、提供者设置和事件捕获模式的权威来源。请先阅读该文件。 2.2. 如果没有匹配的参考文件，可依靠通用知识和网络搜索。以posthog.com/docs作为主要搜索来源。

步骤3：安装PostHog SDK（若已设置PostHog则跳过）

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

步骤4：初始化PostHog（若已设置PostHog则跳过）

遵循框架参考文件中的说明，确定初始化的位置和方式。不同框架的差异较大（例如，Next.js 15.3+使用instrumentation-client.ts，Django使用AppConfig.ready()，Flask使用create_app()）。

步骤5：规划事件追踪

从项目文件列表中选择10至15个可能具有业务价值的文件用于事件追踪，尤其是转化和流失相关事件。
同时查找与登录相关的文件，这些文件可用于标识用户，以及错误处理相关文件。
查找已有的
```
posthog.capture()
```
代码。记录事件名称的格式。请勿重复现有事件，而是对其进行补充。
仅追踪操作，不追踪页面浏览（页面浏览可自动捕获）。对于转化漏斗顶部的“查看”类事件可例外处理。
如果项目包含可埋点的服务端代码（API路由、服务端操作、Webhook处理器、支付/结账完成、认证端点），则必须添加服务端事件。

步骤6：实现事件捕获

为每个规划的事件添加
```
posthog.capture()
```
调用，并附带有用的属性。
如果文件中已存在其他工具或服务的集成代码，请勿覆盖或删除该代码。将PostHog代码放在其下方。
请勿更改现有文件的基础架构。仅进行最小且有针对性的添加。
在尝试写入文件之前，必须先阅读该文件。

步骤7：标识用户

在客户端的登录和注册事件中添加PostHog
```
identify()
```
调用。使用登录和注册表单的内容，在提交时标识用户。
如果同时存在前端和后端，请使用
```
X-POSTHOG-DISTINCT-ID
```
和
```
X-POSTHOG-SESSION-ID
```
标头，将客户端会话和唯一ID传递给服务端代码。在服务端，确保事件具有匹配的唯一ID。

步骤8：添加错误追踪

在相关文件中添加PostHog异常捕获错误追踪，尤其是关键用户流程和API边界附近的文件。

步骤9：设置环境变量

如果已连接env-file-tools MCP服务器，使用check_env_keys查看已存在的密钥，然后使用set_env_values创建或更新PostHog API密钥和主机地址。
在代码中引用这些环境变量，而非硬编码。

步骤10：验证与清理

检查项目是否存在错误。查看package.json中的类型检查或构建脚本。
确保创建的所有组件均已实际使用。
运行package.json中找到的任何代码检查或格式化脚本（如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-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-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-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

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-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-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-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/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 docs: Follow the framework reference's initialization and capture patterns exactly.

环境变量：始终使用环境变量存储PostHog密钥。切勿硬编码。
最小改动：将PostHog代码添加到现有集成代码旁边。请勿替换或重构现有代码。
遵循文档：严格按照框架参考文件中的初始化和捕获模式执行。