Back to Details

integration-javascript_web

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PostHog integration for JavaScript Web

JavaScript Web应用的PostHog集成方案

This skill helps you add PostHog analytics to JavaScript Web applications.
本技能可帮助你为JavaScript Web应用添加PostHog分析功能。

Workflow

工作流程

Follow these steps in order to complete the integration:
  1. basic-integration-1.0-begin.md
    - PostHog Setup - Begin ← Start here
  2. basic-integration-1.1-edit.md
    - PostHog Setup - Edit
  3. basic-integration-1.2-revise.md
    - PostHog Setup - Revise
  4. basic-integration-1.3-conclude.md
    - PostHog Setup - Conclusion
按照以下步骤完成集成：
  1. basic-integration-1.0-begin.md
    - PostHog设置 - 开始 ← 从此处启动
  2. basic-integration-1.1-edit.md
    - PostHog设置 - 编辑
  3. basic-integration-1.2-revise.md
    - PostHog设置 - 修改
  4. basic-integration-1.3-conclude.md
    - PostHog设置 - 总结

Reference files

参考文件

  • references/js.md
    - JavaScript web - docs
  • references/posthog-js.md
    - PostHog JavaScript web SDK
  • references/identify-users.md
    - Identify users - docs
  • references/basic-integration-1.0-begin.md
    - PostHog setup - begin
  • references/basic-integration-1.1-edit.md
    - PostHog setup - edit
  • references/basic-integration-1.2-revise.md
    - PostHog setup - revise
  • references/basic-integration-1.3-conclude.md
    - PostHog setup - conclusion
The example project shows the target implementation pattern. Consult the documentation for API details.
  • references/js.md
    - JavaScript Web - 文档
  • references/posthog-js.md
    - PostHog JavaScript Web SDK
  • references/identify-users.md
    - 用户识别 - 文档
  • references/basic-integration-1.0-begin.md
    - PostHog设置 - 开始
  • references/basic-integration-1.1-edit.md
    - PostHog设置 - 编辑
  • references/basic-integration-1.2-revise.md
    - PostHog设置 - 修改
  • references/basic-integration-1.3-conclude.md
    - PostHog设置 - 总结
示例项目展示了目标实现模式。如需了解API详情，请查阅相关文档。

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.
  • 环境变量：始终使用环境变量存储PostHog密钥，绝不要硬编码。
  • 最小改动：在现有集成代码旁添加PostHog代码，不要替换或重构现有代码。
  • 匹配示例：你的实现应尽可能贴近示例项目的模式。

Framework guidelines

框架指南

  • Remember that source code is available in the node_modules directory
  • Check package.json for type checking or build scripts to validate changes
  • posthog-js is the JavaScript SDK package name
  • posthog.init() MUST be called before any other PostHog methods (capture, identify, etc.)
  • posthog-js is browser-only — do NOT import it in Node.js or server-side contexts (use posthog-node instead)
  • Autocapture is ON by default with posthog-js (tracks clicks, form submissions, pageviews). Do NOT disable autocapture unless the user explicitly requests it.
  • NEVER send PII in posthog.capture() event properties — no emails, full names, phone numbers, physical addresses, IP addresses, or user-generated content
  • PII belongs in posthog.identify() person properties (email, name, role), NOT in capture() event properties
  • Call posthog.identify(userId, { email, name, role }) on login AND on page refresh if the user is already logged in
  • Call posthog.reset() on logout to unlink future events from the current user
  • For SPAs without a framework router, capture pageviews with posthog.capture($pageview) or use the capture_pageview history_change option in init for History API routing
  • 请记住源代码位于node_modules目录中
  • 检查package.json中的类型检查或构建脚本，以验证更改
  • posthog-js是JavaScript SDK的包名
  • 必须先调用posthog.init()，才能调用任何其他PostHog方法（如capture、identify等）
  • posthog-js仅适用于浏览器环境——请勿在Node.js或服务器端上下文导入它（请改用posthog-node）
  • posthog-js默认开启自动捕获功能（跟踪点击、表单提交、页面浏览）。除非用户明确要求，否则请勿禁用自动捕获。
  • 绝不要在posthog.capture()事件属性中发送个人身份信息（PII）——包括邮箱、全名、电话号码、物理地址、IP地址或用户生成内容
  • 个人身份信息应放在posthog.identify()的用户属性中（如邮箱、姓名、角色），而非capture()的事件属性中
  • 在用户登录时以及页面刷新（若用户已登录）时调用posthog.identify(userId, { email, name, role })
  • 用户登出时调用posthog.reset()，以解除后续事件与当前用户的关联
  • 对于无框架路由的单页应用（SPA），可使用posthog.capture($pageview)捕获页面浏览，或在init中使用capture_pageview的history_change选项来适配History API路由

Identifying users

用户识别

Identify users during login and signup events. Refer to the example code and documentation for the correct identify pattern for this framework. If both frontend and backend code exist, pass the client-side session and distinct ID using 
X-POSTHOG-DISTINCT-ID
and 
X-POSTHOG-SESSION-ID
headers to maintain correlation.
在登录和注册事件中识别用户。请参考示例代码和文档，了解适用于该框架的正确识别模式。若同时存在前端和后端代码，请使用
X-POSTHOG-DISTINCT-ID
和
X-POSTHOG-SESSION-ID
标头传递客户端会话和唯一ID，以保持关联。

Error tracking

错误追踪

Add PostHog error tracking to relevant files, particularly around critical user flows and API boundaries.
在相关文件中添加PostHog错误追踪，尤其是关键用户流程和API边界附近。