Back to Details

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)

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

  1. Clarify goals and constraints: business questions, lifecycle stages, identity model, privacy/consent requirements, platforms (web/mobile/backend).
  2. Define the North Star value event: one canonical event that represents value received (plus the smallest set of supporting events).
  3. Write the tracking plan: use 
    assets/tracking-plan-saas.md
    as the starting template; define required properties and ownership.
  4. Implement instrumentation: pick the platform guide in Quick Reference (PostHog/Pendo/Amplitude/Mixpanel/Heap; server-side if needed).
  5. QA and harden: use 
    assets/analytics-qa-checklist.md
    + 
    references/event-quality-rules.md
    + 
    references/production-hardening.md
    .
  1. 明确目标与约束：业务问题、生命周期阶段、身份模型、隐私/同意要求、平台（网页/移动端/后端）。
  2. 定义北极星价值事件：一个代表用户获取价值的标准事件（加上最少的配套事件）。
  3. 编写追踪方案：以
    assets/tracking-plan-saas.md
    为起始模板；定义必填属性及负责人。
  4. 实施埋点：参考快速参考中的平台指南（PostHog/Pendo/Amplitude/Mixpanel/Heap；必要时使用服务端追踪）。
  5. 质量保证与优化：使用
    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 TypeNorth Star EventWhen 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.
LayerRequired EventsOptional
Acquisition
page_viewed
, 
signup_completed
campaign_landed
ActivationYour activation event (1-2 max)
onboarding_step_completed
EngagementYour 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. 会话上下文注册

Register standard context once per session using 
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. 事件命名规范

RuleCorrectIncorrect
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

快速参考

TaskReference
PostHog setupreferences/posthog-implementation.md
Pendo setupreferences/pendo-implementation.md
Amplitude setupreferences/amplitude-implementation.md
Mixpanel setupreferences/mixpanel-implementation.md
Heap setupreferences/heap-implementation.md
Server-side trackingreferences/server-side-tracking.md
Privacy compliancereferences/privacy-compliance.md
Event quality rulesreferences/event-quality-rules.md
Production patternsreferences/production-hardening.md
Tracking plan templateassets/tracking-plan-saas.md
UTM standardsassets/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-PatternInstead
No North Star eventDefine ONE canonical activation event
Excessive 
*_viewed
events		Collapse into one event with properties
PII in identify()State-based identification only
Event spam from re-rendersUse 
isPostHogReady()
guard + dedupe
Free text 
source
Use TypeScript enum for TrafficSource
Non-unique IDsUse stable domain IDs (
*_id
) or an action_instance_id
Tracking everythingFocus on 5-15 key events (MVA)
Inconsistent namingEnforce 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

模板

TemplatePurpose
tracking-plan-saas.mdComplete SaaS tracking plan
marketing-event-library.mdMarketing attribution events
utm-naming-standards.mdUTM parameter guide
activation-metrics-template.mdActivation metric definition
analytics-qa-checklist.mdData quality checklist
模板用途
tracking-plan-saas.md完整的SaaS追踪方案
marketing-event-library.md营销归因事件库
utm-naming-standards.mdUTM参数指南
activation-metrics-template.md激活指标定义模板
analytics-qa-checklist.md数据质量检查清单

International Markets

国际市场适配

This skill uses US/UK market defaults. For international product analytics:
NeedSee Skill
Regional compliance (GDPR, PIPL, LGPD)marketing-geo-localization
Regional analytics platforms (Baidu Analytics)marketing-geo-localization
Privacy requirements by regionmarketing-geo-localization
Cookie consent by jurisdictionmarketing-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与本技能。

Related Skills

相关技能

  • marketing-cro - A/B testing, conversion optimization
  • marketing-leads-generation - Lead funnel, B2B attribution
  • qa-agent-testing - LLM agent testing (complements AI analytics)
  • data-sql-optimization - SQL for analytics queries
  • marketing-cro - A/B测试、转化优化
  • marketing-leads-generation - 线索漏斗、B2B归因
  • qa-agent-testing - LLM Agent测试（补充AI分析）
  • data-sql-optimization - 用于分析查询的SQL优化

Data Sources

数据源

See data/sources.json for official documentation links.
官方文档链接请参见data/sources.json。