marketing-product-analytics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Product Analytics - Instrumentation & Measurement OS

产品分析 - 埋点与度量系统

Modern Best Practices (January 2026): PostHog-first, session context registration, strict event naming, North Star activation events, privacy-first attribution.

Primary sources live in

data/sources.json

. If web search is available, refresh time-sensitive details against official docs before giving definitive advice.

No fluff. Only executable steps, templates, and checklists.

2026年1月现代最佳实践：以PostHog为首选、会话上下文注册、严格的事件命名、北极星激活事件、隐私优先的归因。

主要数据源位于

data/sources.json

。如果可以进行网页搜索，在给出明确建议前，请对照官方文档刷新时效性内容。

拒绝冗余内容，仅提供可执行步骤、模板和检查清单。

When to Use This Skill

何时使用此技能

Event taxonomy design: Naming conventions, event hierarchy, property structure
Tracking plan creation: What to track, where, and why
Marketing attribution: UTM capture, campaign tracking, source attribution
Activation metrics: Defining and measuring user activation
Retention analysis: Cohort analysis, churn prediction, engagement scoring
Platform setup: PostHog, Pendo, Amplitude, Mixpanel, Heap configuration
Data quality: Event validation, debugging, governance

事件分类设计：命名规范、事件层级、属性结构
追踪方案创建：需要追踪的内容、位置及原因
营销归因：UTM参数捕获、活动追踪、来源归因
激活指标：定义并衡量用户激活
留存分析： cohort分析、流失预测、参与度评分
平台配置：PostHog、Pendo、Amplitude、Mixpanel、Heap的设置
数据质量：事件验证、调试、治理

Default Workflow (Use Unless User Overrides)

默认工作流（用户未指定时使用）

Clarify goals and constraints: business questions, lifecycle stages, identity model, privacy/consent requirements, platforms (web/mobile/backend).
Define the North Star value event: one canonical event that represents value received (plus the smallest set of supporting events).
Write the tracking plan: use
```
assets/tracking-plan-saas.md
```
as the starting template; define required properties and ownership.
Implement instrumentation: pick the platform guide in Quick Reference (PostHog/Pendo/Amplitude/Mixpanel/Heap; server-side if needed).

QA and harden: use

assets/analytics-qa-checklist.md

references/event-quality-rules.md

references/production-hardening.md

明确目标与约束：业务问题、生命周期阶段、身份模型、隐私/同意要求、平台（网页/移动端/后端）。
定义北极星价值事件：一个代表用户获取价值的标准事件（加上最少的配套事件）。
编写追踪方案：以
```
assets/tracking-plan-saas.md
```
为起始模板；定义必填属性及负责人。
实施埋点：参考快速参考中的平台指南（PostHog/Pendo/Amplitude/Mixpanel/Heap；必要时使用服务端追踪）。

质量保证与优化：使用

assets/analytics-qa-checklist.md

references/event-quality-rules.md

references/production-hardening.md

。

Core Principles

核心原则

1. North Star Value Event (VITAL)

1. 北极星价值事件（至关重要）

Every product must have ONE canonical activation event - the single event that means "user received real value."

Product Type	North Star Event	When It Fires
Content/Media	`content_consumed`	Content fully loaded and visible
SaaS Tool	`workflow_completed`	User completes core workflow
E-commerce	`purchase_completed`	Transaction successful
Developer Tool	`integration_working`	First successful API call

Rule: Every feature event should collapse into ONE activation event with properties:

javascript

// PASS CORRECT: One event, differentiated by property
posthog.capture('value_delivered', { value_type: 'report', value_id: 'rpt_123' });
posthog.capture('value_delivered', { value_type: 'integration', value_id: 'int_456' });

// FAIL WRONG: Fragmented "value" events (harder to unify in retention/funnels)
posthog.capture('report_generated');
posthog.capture('integration_working');

每个产品必须有一个标准的激活事件——即代表“用户获得实际价值”的单一事件。

产品类型	北极星事件	触发时机
内容/媒体类	`content_consumed`	内容完全加载并可见
SaaS工具类	`workflow_completed`	用户完成核心工作流
电商类	`purchase_completed`	交易成功
开发者工具类	`integration_working`	首次API调用成功

规则：每个功能事件应合并为一个带属性的激活事件：

javascript

// 正确示例：单个事件，通过属性区分
posthog.capture('value_delivered', { value_type: 'report', value_id: 'rpt_123' });
posthog.capture('value_delivered', { value_type: 'integration', value_id: 'int_456' });

// 错误示例：碎片化的“价值”事件（在留存/漏斗分析中难以统一）
posthog.capture('report_generated');
posthog.capture('integration_working');

2. Minimum Viable Analytics (MVA)

2. 最小可行分析（MVA）

Start with 5-15 events, not 200. You can always add more.

Layer	Required Events	Optional
Acquisition	`page_viewed` , `signup_completed`	`campaign_landed`
Activation	Your activation event (1-2 max)	`onboarding_step_completed`
Engagement	Your engagement signal (1-2 max)	`feature_used`
Conversion	`purchase_completed`	`checkout_started`

从5-15个事件开始，而非200个。后续可逐步添加更多事件。

层级	必填事件	可选事件
获客	`page_viewed` , `signup_completed`	`campaign_landed`
激活	你的激活事件（最多1-2个）	`onboarding_step_completed`
参与	你的参与信号（最多1-2个）	`feature_used`
转化	`purchase_completed`	`checkout_started`

3. Session Context Registration

3. 会话上下文注册

posthog.register()

typescript

posthog.register({
  app_env: 'prod',
  platform: 'web',
  landing_path: window.location.pathname,
  traffic_source: deriveTrafficSource(),
  utm_source, utm_medium, utm_campaign
});

使用

posthog.register()

在每个会话中注册一次标准上下文：

typescript

posthog.register({
  app_env: 'prod',
  platform: 'web',
  landing_path: window.location.pathname,
  traffic_source: deriveTrafficSource(),
  utm_source, utm_medium, utm_campaign
});

4. Event Naming Convention

4. 事件命名规范

Rule	Correct	Incorrect
Lowercase only	`user_signed_up`	`User_Signed_Up`
Snake_case	`button_clicked`	`buttonClicked`
Object_action format	`project_created`	`createProject`

规则	正确示例	错误示例
仅使用小写	`user_signed_up`	`User_Signed_Up`
蛇形命名法（Snake_case）	`button_clicked`	`buttonClicked`
对象_动作格式	`project_created`	`createProject`

Quick Reference

快速参考

Task	Reference
PostHog setup	references/posthog-implementation.md
Pendo setup	references/pendo-implementation.md
Amplitude setup	references/amplitude-implementation.md
Mixpanel setup	references/mixpanel-implementation.md
Heap setup	references/heap-implementation.md
Server-side tracking	references/server-side-tracking.md
Privacy compliance	references/privacy-compliance.md
Event quality rules	references/event-quality-rules.md
Production patterns	references/production-hardening.md
Tracking plan template	assets/tracking-plan-saas.md
UTM standards	assets/utm-naming-standards.md

任务	参考文档
PostHog配置	references/posthog-implementation.md
Pendo配置	references/pendo-implementation.md
Amplitude配置	references/amplitude-implementation.md
Mixpanel配置	references/mixpanel-implementation.md
Heap配置	references/heap-implementation.md
服务端追踪	references/server-side-tracking.md
隐私合规	references/privacy-compliance.md
事件质量规则	references/event-quality-rules.md
生产环境优化	references/production-hardening.md
追踪方案模板	assets/tracking-plan-saas.md
UTM标准	assets/utm-naming-standards.md

Implementation Checklist

实施检查清单

markdown

undefined

markdown

undefined

Event Correctness

事件正确性

Activation event fires only when value is visible (not on mount)
Event includes required properties defined in the tracking plan (e.g.,
```
object_type
```
,
```
object_id
```
,
```
surface
```
,
```
flow
```
)
Dedupe guard used where re-renders can double-fire (see
```
references/production-hardening.md
```
)
Event fires in exactly one place per feature

激活事件仅在价值可见时触发（而非组件挂载时）
事件包含追踪方案中定义的必填属性（如
```
object_type
```
,
```
object_id
```
,
```
surface
```
,
```
flow
```
）
在可能重复渲染导致重复触发的场景中使用去重防护（参见
```
references/production-hardening.md
```
）
每个功能的事件仅在唯一位置触发

Session Context

会话上下文

```
registerSessionContext()
```
called on app init

Includes:

app_env

platform

landing_path

traffic_source

, UTMs

```
registerSessionContext()
```
在应用初始化时调用

包含：

app_env

platform

landing_path

traffic_source

, UTM参数

Type Safety

类型安全

```
TrafficSource
```
uses TypeScript enum, not free string
All properties use
```
snake_case
```

```
TrafficSource
```
使用TypeScript枚举，而非自由文本
所有属性使用
```
snake_case
```

Privacy

隐私

Person properties contain no PII by default
Email only stored with explicit consent

---

用户属性默认不包含任何个人身份信息（PII）
仅在获得明确同意后存储邮箱

---

Decision Tree

决策树

undefined

undefined

Not seeing expected events?

未看到预期事件？

├─ PostHog default events visible? ($pageview, autocapture) │ ├─ Yes -> Custom event bug -> Check component, guards, dedupe │ └─ No -> SDK issue -> Check env vars, consent, ad blockers ├─ Check DevTools Network -> verify /e/ calls └─ Check PostHog Live Events (not Activity)

├─ PostHog默认事件可见吗？（$pageview、自动捕获） │ ├─ 是 -> 自定义事件存在bug -> 检查组件、防护机制、去重逻辑 │ └─ 否 -> SDK问题 -> 检查环境变量、同意设置、广告拦截器 ├─ 检查开发者工具网络面板 -> 验证/e/请求 └─ 检查PostHog实时事件（而非活动）

Can't answer business questions?

无法回答业务问题？

├─ Missing events -> Add custom events for key moments ├─ Missing properties -> Enrich with context ├─ No user ID -> Implement identify() calls └─ Attribution gaps -> Capture UTMs, persist through signup

---

├─ 缺少事件 -> 为关键节点添加自定义事件 ├─ 缺少属性 -> 补充上下文信息 ├─ 无用户ID -> 实施identify()调用 └─ 归因缺口 -> 捕获UTM参数，在注册流程中持久化

---

Anti-Patterns Summary

反模式总结

Anti-Pattern	Instead
No North Star event	Define ONE canonical activation event
Excessive `*_viewed` events	Collapse into one event with properties
PII in identify()	State-based identification only
Event spam from re-renders	Use `isPostHogReady()` guard + dedupe
Free text `source`	Use TypeScript enum for TrafficSource
Non-unique IDs	Use stable domain IDs ( `*_id` ) or an action_instance_id
Tracking everything	Focus on 5-15 key events (MVA)
Inconsistent naming	Enforce lowercase snake_case strictly

See references/event-quality-rules.md for detailed examples.

反模式	正确做法
无北极星事件	定义一个标准的激活事件
过多 `*_viewed` 事件	合并为单个带属性的事件
identify()中包含个人身份信息（PII）	仅基于状态进行身份识别
重复渲染导致事件泛滥	使用 `isPostHogReady()` 防护 + 去重逻辑
自由文本 `source`	为TrafficSource使用TypeScript枚举
非唯一ID	使用稳定的领域ID（ `*_id` ）或action_instance_id
追踪所有事件	聚焦5-15个关键事件（最小可行分析）
命名不一致	严格执行小写蛇形命名法

详细示例参见references/event-quality-rules.md。

Metrics and Benchmarks

指标与基准

Default to internal baselines and trendlines; use external benchmarks only when comparing like-for-like segments and definitions.

If you need external references, see

data/sources.json

benchmarks_research

默认使用内部基线和趋势线；仅在对比同类细分群体和定义时使用外部基准。

如需外部参考，请查看

data/sources.json

benchmarks_research

。

Templates

模板

Template	Purpose
tracking-plan-saas.md	Complete SaaS tracking plan
marketing-event-library.md	Marketing attribution events
utm-naming-standards.md	UTM parameter guide
activation-metrics-template.md	Activation metric definition
analytics-qa-checklist.md	Data quality checklist

模板	用途
tracking-plan-saas.md	完整的SaaS追踪方案
marketing-event-library.md	营销归因事件库
utm-naming-standards.md	UTM参数指南
activation-metrics-template.md	激活指标定义模板
analytics-qa-checklist.md	数据质量检查清单

International Markets

国际市场适配

This skill uses US/UK market defaults. For international product analytics:

Need	See Skill
Regional compliance (GDPR, PIPL, LGPD)	marketing-geo-localization
Regional analytics platforms (Baidu Analytics)	marketing-geo-localization
Privacy requirements by region	marketing-geo-localization
Cookie consent by jurisdiction	marketing-geo-localization

If your query is primarily about GDPR/PIPL/LGPD or consent configuration, use marketing-geo-localization alongside this skill.

本技能默认使用美/英市场规范。针对国际产品分析：

需求	参考技能
区域合规（GDPR、PIPL、LGPD）	marketing-geo-localization
区域分析平台（如百度统计）	marketing-geo-localization
区域隐私要求	marketing-geo-localization
按司法管辖区设置Cookie同意	marketing-geo-localization

如果你的问题主要关于GDPR/PIPL/LGPD或同意配置，请结合使用marketing-geo-localization与本技能。