marketing-product-analytics

产品分析 - 埋点与衡量操作系统

现代最佳实践（2026 年 1 月）：以 PostHog 为先，注册会话上下文，严格规范事件命名，采用北极星激活事件，优先保护隐私的归因。

主要来源位于 data/sources.json。如果可以进行网页搜索，请先根据官方文档更新时效性信息，再给出确定性建议。

不说废话。只提供可执行步骤、模板和检查清单。

---

何时使用此技能

• 事件分类设计：命名规范、事件层级、属性结构
• 跟踪计划创建：跟踪什么、在哪里跟踪以及原因
• 营销归因：UTM 捕获、营销活动跟踪、来源归因
• 激活指标：定义并衡量用户激活
• 留存分析：群组分析、流失预测、参与度评分
• 平台设置：配置 PostHog、Pendo、Amplitude、Mixpanel、Heap
• 数据质量：事件验证、调试、治理

---

默认工作流（除非用户另有要求，否则使用）

1. 明确目标和限制：业务问题、生命周期阶段、身份模型、隐私/同意要求、平台（Web/移动端/后端）。
2. 定义北极星价值事件：一个代表用户获得价值的规范事件（以及最少数量的辅助事件）。
3. 编写跟踪计划：使用 assets/tracking-plan-saas.md 作为起始模板；定义必需属性及其负责人。
4. 实施埋点：在快速参考中选择平台指南（PostHog/Pendo/Amplitude/Mixpanel/Heap；如有需要则采用服务端方案）。
5. QA 并加固：使用 assets/analytics-qa-checklist.md + references/event-quality-rules.md + references/production-hardening.md。

---

核心原则

1. 北极星价值事件（VITAL）

每个产品都必须有一个规范的激活事件 —— 唯一代表“用户获得了实际价值”的事件。

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

规则：每个功能事件都应归并为一个激活事件，并包含以下属性：

// 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');

2. 最小可行分析（MVA）

从 5-15 个事件开始，而不是 200 个。 之后随时可以添加更多事件。

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

对于身份验证流程繁重的产品，应尽早添加电子邮件送达可靠性埋点：

• auth_email_requested（类型：signup_confirm、magic_link、reset_password）
• auth_email_delivered / auth_email_bounced / auth_email_complained（来自服务商 Webhook）
• auth_email_link_clicked（用于衡量完成质量的信号，而不仅仅是发送量）

3. 会话上下文注册

每个会话使用一次 posthog.register() 注册标准上下文：

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

4. 事件命名规范

规则	正确示例	错误示例
仅使用小写字母	user_signed_up	User_Signed_Up
使用 Snake case	button_clicked	buttonClicked
对象_动作格式	project_created	createProject

---

快速参考

任务	参考资料
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
漏斗分析	references/funnel-analysis.md
Cohort 留存分析	references/cohort-retention-analysis.md
实验	references/experimentation-framework.md
用户细分	references/user-segmentation.md
数据治理	references/data-governance.md
会话回放与热力图	references/session-replay-heatmaps.md
归因建模	references/attribution-modeling.md
跟踪计划模板	assets/tracking-plan-saas.md
UTM 规范	assets/utm-naming-standards.md

---

实施检查清单

### 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

### Session Context
- [ ] `registerSessionContext()` called on app init
- [ ] Includes: `app_env`, `platform`, `landing_path`, `traffic_source`, UTMs

### Type Safety
- [ ] `TrafficSource` uses TypeScript enum, not free string
- [ ] All properties use `snake_case`

### Privacy
- [ ] Person properties contain **no PII** by default
- [ ] Email only stored with explicit consent

---

决策树

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

### 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

---

反模式摘要

反模式	应采取的做法
没有北极星事件	定义一个规范的激活事件
过多的 *_viewed 事件	合并为一个带属性的事件
在 identify() 中包含 PII	仅基于状态进行识别
重渲染导致事件泛滥	使用 isPostHogReady() 防护条件并去重
source 使用自由文本	使用 TypeScript 枚举表示 TrafficSource
ID 不唯一	使用稳定的领域 ID（*_id）或 action_instance_id
跟踪所有内容	聚焦于 5-15 个关键事件（MVA）
命名不一致	严格采用小写 snake_case

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

---

指标与基准

优先使用内部基线和趋势线；仅在比较定义和细分群体一致的数据时，才使用外部基准。

如需外部参考资料，请查看 data/sources.json -> benchmarks_research。

---

模板

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

---

国际市场

此技能使用美国/英国市场的默认设置。对于国际产品分析：

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

如果你的查询主要涉及 GDPR/PIPL/LGPD 或同意配置，请结合此技能使用 marketing-geo-localization。

---

相关技能

• marketing-cro - A/B 测试、转化优化
• marketing-leads-generation - 线索漏斗、B2B 归因
• qa-agent-testing - LLM Agent 测试（补充 AI 分析）
• data-sql-optimization - 用于分析查询的 SQL

---

数据来源

请参阅 data/sources.json 中的官方文档链接。

运维手册：埋点门禁（PR 前）

使用此流程确保分析变更适用于生产环境且可供查询。

PR 前命令

# 1) Find changed tracking calls
rg -n "capture\(|track\(|analytics\.|posthog\." src app lib

# 2) Enforce event/property naming policy
rg -n "[A-Z]" src | rg "capture\(|track\("  # quick camelCase/PascalCase smell

# 3) Validate tracking plan coverage
# (keep a single source of truth file; fail if event is missing)
rg -n "signup_started|signup_completed|checkout_started|trial_started" docs src

# 4) Run analytics gate test (if project defines one)
npm run test:analytics-gate

部署后冒烟查询模板

-- Replace table names for your warehouse/provider
select event,
       count(*) as events,
       count(distinct distinct_id) as users
from events
where timestamp >= now() - interval '24 hour'
  and event in ('signup_started','signup_completed','checkout_started','trial_started')
group by event
order by events desc;

事件契约最低要求

每个关键事件必须包含：

• 稳定的事件名称（snake_case）
• 操作者 ID（user_id 或 distinct_id）
• 对象 ID（*_id）
• 来源上下文（相关时包括 surface、entry_point、utm_*）
• 来自服务器或可信客户端时钟的时间戳

门禁失败策略

• 缺少关键事件或必需属性：阻止合并。
• 非关键属性发生变化：仅在创建后续问题时允许合并。
• 静默重命名事件：在准备好仪表板/查询迁移之前阻止合并。