product-analytics-setup

产品分析设置

资深产品经理和分析师首次正确埋点的实战指南。

大多数产品分析设置都混杂着沿袭下来的错误、泛滥的仪表板，以及无人信任的事件。团队推出一项新功能；埋点在截止期限的压力下匆忙添加；命名逐渐偏离规范；属性各不一致；六个月后，没人能回答简单的问题，因为答案取决于你信任哪个事件。

这项技能旨在防止这种情况。它假设你已经回答了关于要衡量什么的战略问题（参见 analytics-strategy）。它还假设你已连接某种工具（Mixpanel、Heap、PostHog、Amplitude，或通过 BigQuery、Snowflake 或 dbt 使用数据仓库原生工具）。难点在于系统化执行：命名规范、属性设计、架构版本管理、漏斗构建、群组定义和留存衡量。

适用场景：从头设置产品分析、审计现有埋点、解决“有数据但无法信任”的问题，或为新功能设计埋点。

---

本技能的用途

本技能涵盖埋点执行。不涉及衡量策略（使用 analytics-strategy）、实验结果解读（使用 experimentation-analytics）、付费媒体分析（使用 ads-performance-analytics）或平台决策（使用 experimentation-platform-orchestrator）。请将本技能与适用于你所用工具的集成微站搭配使用。

与 analytics-strategy 的明确区别在于：该技能（Growth 类别）侧重战略：衡量什么以及为什么、KPI 层级、仪表板架构、归因模型。本技能（Product 类别）侧重执行：如何正确地为产品埋点。两者相辅相成。先阅读 analytics-strategy，确定哪些事项重要；再阅读本技能，为其进行埋点。

---

埋点层级

思维模型：每套分析设置都由多个层级组成。每一层都依赖其下方层级的准确性。

• 事件是原子事实：user_signed_up、checkout_completed、feature_x_used。
• 属性描述事件：谁、什么、何处、何时，以及相关上下文。
• 身份标识将事件关联到用户：anonymous_id、user_id、account_id。
• 群组是跨事件的筛选条件：“3 月通过付费渠道获取的用户”。
• 漏斗是事件序列：注册，然后激活，然后首次执行付费操作。
• 留存衡量重复行为：第 N 周仍活跃的注册用户。

如果底层层级不准确，就无法构建更高层级。无效事件会产生无效漏斗。这套方法应自下而上。大多数“有数据但无法信任”的问题都源于最底下两个层级。

---

事件分类设计

事件设计的三条规则。

1. 过去时，面向动作。 使用 checkout_completed，而不是 checkout_complete 或 completing_checkout。过去时表示“这件事已经发生”，而不是一种状态。
2. 对象-动作格式。 名词在前，动词在后。video_played、form_submitted、email_opened。把事件名称读出来，就应该能描述发生了什么。
3. 粒度明确，但不冗余。 记录不同的用户操作，而不是按钮点击。只在完成的那一刻触发一次 checkout_completed，不要同时触发 submit_button_clicked 和 checkout_completed。UI 事件是噪声；语义事件才是信号。

动词与状态的陷阱。

• 动词就是事件。checkout_completed、subscription_canceled、account_upgraded。
• 状态不是事件，而是属性。user_status: active 是用户的属性，不是事件。通过事件设置状态（status_changed_to_active）是一种代码异味，会导致重复计数。

应该设计多少个事件？对于典型的 SaaS 产品，30 到 50 个事件最合适。少于 20 个表示埋点不足；超过 100 个通常意味着记录了 UI 噪声，或以不同格式重复记录了事件。

详见 references/event-taxonomy-template.md 中的事件规范范例。

---

属性设计：事件级与用户级

两种属性类型，应分别处理。

事件级属性描述的是本次事件。checkout_completed 事件包含 cart_value、item_count、payment_method、discount_code 等属性。它们保存在事件负载中，触发后不可更改。

用户级属性描述的是用户随时间的变化。subscription_tier、lifetime_value、acquisition_channel。在用户资料上设置一次；分析工具会将这些属性关联到该用户触发的每个事件。用户发生变化时，这些属性也会随之更新。

陷阱：在每个事件上都放入用户级属性。不要在每个事件负载中记录 subscription_tier；只需在用户资料上设置一次，并依赖关联操作即可。将它放入事件中会造成负载膨胀、值变化时的架构漂移，以及用户在会话中途升级时的报告混乱。

数据类型规范。

• 字符串用于枚举值：状态、等级、渠道、地区。适用于取值范围有限的值。
• 数字仅用于实际的数值：计数、金额、时长、分数。切勿用字符串表示数值数据（“免费试用第 7 天”应写作 trial_day: 7）。
• 布尔值用于实际的布尔数据：is_admin、has_trial、is_new_user。仅有两个值，不包含其他值。
• 时间戳始终使用 ISO 8601。始终如此。不一致的日期格式会造成无数错误。
• 数组应少用。数组属性通常意味着你应该拆分为多个事件，每个事件包含一项。

references/property-design-patterns.md 提供了 product_viewed 事件的正确与错误设计示例。

---

命名约定

选择并严格执行一种约定。以下三种约定值得考虑。

• 事件和属性使用 snake_case：user_signed_up、cart_value。大多数平台默认使用这种格式；通常不值得为此争论。
• 事件使用 对象-动作格式：user_signed_up、video_played。名称应能描述发生了什么。
• 用户属性使用 动词-名词格式（或直接使用名词）：subscription_tier、is_admin、last_active_at。

不要这样做。

• 同一项目中的事件大小写风格混杂。user_signedUp、User Signed Up、userSignedUp 同时存在。选定一种并迁移。
• 事件或属性名称中包含空格。“Sign Up Completed”会破坏各种 URL 编码场景，也会让所有工具感到困惑。
• 动词使用不一致。同一项目中同时出现 user_signed_up、completedCheckout 和 VIEW_PRODUCT，意味着没人能不查找就预测事件名称。
• 事件名称中包含品牌名。从 Mailchimp 切换到 Customer.io 后，mailchimp_email_opened 就会显得过时。

命名约定参考文件提供了完整的风格指南。请在团队的数据契约中引用它。

详见 references/naming-convention-reference.md。

---

架构版本控制

架构变更不可避免。推荐采用以下模式。

增量变更是安全的。新增事件、为现有事件新增属性、为枚举新增值。直接发布即可。现有仪表板会继续正常工作。

破坏性变更需要迁移。重命名事件、移除属性、更改属性类型、缩小枚举范围。这些变更会破坏下游仪表板；迁移计划是变更的一部分。

版本控制模式。

• 语义发生变化时，在事件名称后追加 _v2。过渡期间，checkout_completed_v2 会与 checkout_completed 同时触发。
• 过渡期间继续触发旧事件（通常为 90 天）。两个版本都会触发；分析查询会逐步迁移到 v2。
• 在停用 v1 之前，将仪表板迁移到 v2。然后通过文档说明明确弃用 v1。

数据契约的思路。

• 在代码中记录规范架构：TypeScript 接口、JSON Schema 或 Protobuf 定义。
• 对每次架构变更进行代码审查。架构是产品的一部分，而非事后考虑的事项。
• CI lint 会在违反架构的内容进入生产环境之前将其拒绝。添加了类型错误事件的部署会导致构建失败。

详见 references/schema-versioning-patterns.md。

---

漏斗设计

漏斗用于衡量用户在一系列步骤中的进展。四条规则。

1. 顺序很重要。 A 然后 B 再然后 C，与 B 然后 A 再然后 C 是不同的漏斗。平台会根据顺序计算不同的转化率。
2. 时间窗口很重要。 大多数漏斗使用从首个事件开始计算的 1 至 30 天窗口。请明确记录时间窗口；“完成注册并激活的用户”如果没有“在 14 天内”，就毫无意义。
3. 流失的解读很难。 80％ 的用户在第 2 步流失，原因可能是漏斗设计（受众不对）、受众本身（时机不对），也可能是产品（确实发生了流失）。下结论之前先调查。
4. 锚点事件模式。 每个漏斗都应从高意向行为开始：注册、开始试用、使用关键功能。不要使用 page_view 或 session_start 这类虚荣事件。以虚荣事件为锚点的漏斗会显示 99％ 的流失，毫无参考价值。

常见的漏斗错误。

• 漏斗包含自动触发的事件。每次访问都会发生 session_started；将其用作一个步骤会抬高分母，让漏斗其余部分失去意义。
• 漏斗过长（10 个或更多步骤）。拆分为两个或三个较短的漏斗。10 步漏斗的端到端转化率几乎为零，难以解读。
• 漏斗在多个位置包含相同事件。平台对此处理不佳；分析人员处理得更糟。
• 在一个漏斗中混用不同的时间窗口。“在 7 天内注册并在 30 天内转化的用户”是两个不同的群组定义拼接而成的。

references/funnel-design-templates.md 中介绍了常见的漏斗形态和时间窗口指南。

---

群组定义

群组是共享某种属性或行为的一组用户。常见的实用模式如下。

• 获客群组。 在 X 月获客的用户。留存分析的标准做法。
• 行为群组。 完成操作 Y 的用户。适用于激活分析（“第 1 周发送过首条消息的用户”）。
• 属性群组。 subscription_tier: pro 的用户。适用于细分层级分析。
• 组合群组。 3 月注册且完成引导流程并且位于欧盟的用户。实际分析工作中最常见的群组。

群组管理规范。

• 在代码中（或使用工具的已保存群组功能）定义群组，以便重复使用。
• 条件发生变化时，为群组创建新版本。确保比较的是同类数据。
• 不要将创建满 30 天的群组与创建满 365 天的群组进行留存比较；按定义，较早的群组有更多时间留存。

详见 references/cohort-definition-patterns.md。

---

留存衡量

留存是随时间重复发生的行为。分为三种。

• N 日留存。 用户 X 是否恰好在第 7 天、第 14 天或第 30 天回来。任何单独一天的数据噪声都较大；适用于周期较短的产品。
• 区间留存。 用户 X 是否在第 7 至 13 周期间的任意时间回来。比 N 日留存更稳定，在留存曲线上也更清晰。
• 不设上限（滚动）留存。 用户 X 是否在注册后的任意时间回来。适用于周期较长、每周使用频率可能产生误导的产品。

对于大多数 SaaS 产品，区间留存是合适的默认选项。第 7 天的数据噪声较大；第 2 周（区间）更稳定。第 1 天留存几乎总是过度反映引导流程的效果，而非产品市场契合度信号。

留存曲线解读。

• 早期急剧下降，随后趋于平稳。产品拥有核心用户；其余用户很快流失。这是大多数 SaaS 产品的典型情况。
• 数周内逐渐衰减，没有平台期。没有用户留下来。通常是价值主张或引导流程存在问题；产品未能持续提供价值。
• 低百分比处保持平稳。拥有少量活跃用户的高级用户型产品。这不是问题，只是曲线形态不同。

详见 references/retention-measurement-patterns.md。

---

北极星指标与配套指标

北极星指标（NSM）的选择规则。

• 体现用户价值，而不只是公司价值。
• 捕捉核心行动：该行动增长时，业务也随之增长。
• 能够在不同时间段保持一致地衡量。
• 难以操纵。

不理想的 NSM：注册数（虚荣指标；许多注册用户从未激活）。收入（滞后指标；不以行动为导向；随业务组合而变化）。DAU（仅适用于由互动驱动的产品；用于月度使用频率的产品时会造成误导）。

更好的 NSM：每周活跃编辑者（Figma）。预订晚数（Airbnb）。每日发送的消息数（Slack）。每个工作区每周创建的产品数（Linear）。每项指标都指向一项体现用户价值、并与业务增长相对应的行动。

配套指标框架。

• 一个 NSM。
• 三到五个推动 NSM 的输入指标。以“每周活跃编辑者”为例，可以包括：每周注册数、注册到活跃用户的转化率、活跃用户的周环比留存率。
• 五到十个用于预警问题的健康指标。月流失率、账户层面的集中度、支持工单量。

详见 references/north-star-metric-selection.md 中的产品类型专属示例和详细说明。

---

值得信赖的仪表板原则

满足以下四个条件，仪表板才值得信赖。

1. 每项指标都有清晰的定义，并记录在文档中。不是“活跃用户”，而是“过去 7 天内触发过任意事件的用户，按 user_id 去重，并排除员工”。
2. 每项指标都有明确的数据来源。 不是“来自数据仓库”，而是“来自 fct_orders，取最近 30 天的数据，并与 dim_customers 联接”。
3. 每项指标都有已知的注意事项。 不包含建模的 iOS 转化。不包含内部员工。不包含 QA 账户中的测试用户。
4. 每项指标都可复现。 明天运行相同的查询，对同一时间段会得到相同的数字。

仪表板过时的失效模式：两年前构建的仪表板仍在使用。底层架构已变更，仪表板的查询指向已不存在或含义已改变的列。团队依据错误数据做出决策，直到严重问题出现时才意识到出了错。

预防措施：每个仪表板都有负责人、刷新频率和季度审查。没有负责人的仪表板将被弃用。90 天未刷新的仪表板将被弃用。仪表板的半衰期比产品的半衰期更短。

---

埋点债务

偷工减料会产生不断累积的成本。

• 新功能上线时未添加埋点：节省 1 小时。
• 六个月后：没人能回答“功能 X 是否有效？”
• 事后补充埋点的成本：20 小时（重新部署、回填、验证）。
• 空缺期间错失决策的成本：无法追踪，但确实存在。决策依据直觉而非数据；有时直觉是错的。

埋点债务确实存在，其累积方式与技术债务类似。相关规范如下。

• 每个新增功能的 PR 都要包含埋点。PR 模板会询问“此功能会触发哪些事件？”，如果答案是没有，则拒绝该 PR。
• 每季度审查一次架构。找出孤立事件（会触发，但未用于任何仪表板或查询）并弃用。找出缺口（没有事件的功能）并补齐。
• “无法衡量就不上线”，但对真正的实验性功能明确例外：此类功能的埋点成本可能超过数据价值。

详见 references/instrumentation-audit-checklist.md。

---

常见故障模式

产品分析设置中反复出现 12 种模式。简而言之：

• “我们有数据，但无法信任它。”命名和架构发生漂移。解决方法是审核架构，并强制执行命名规范。
• “我们的漏斗显示流失率为 80%，但实际转化情况不错。”锚点事件或时间窗口有误。修正漏斗定义。
• “留存曲线在 5% 处持平。”这通常不是问题。面向重度用户的产品确实可能只有一小部分活跃用户。在将其视为待修复问题前，先对照业务实际情况。
• “Mixpanel 显示有 1000 次转化，数据仓库却显示 800 次。”归因和身份关联不一致。与数据仓库核对，以确定规范数字。
• “仪表板需要 30 秒才能加载。”查询范围过宽、属性未编入索引，或架构臃肿。分析性能并重构。
• “每个人对 MAU 的定义都不一样。”缺少规范的指标文档。发布一份，并要求所有人使用相同定义。
• “我们记录了每次按钮点击。”这是 UI 噪声。审核并移除未用于任何仪表板或查询的事件。
• “我们的事件名称改过三次。”没有版本控制。迁移到版本化模式，并停止进一步重命名。
• “分析工具显示 iOS 用户转化率为 3%，但数据仓库显示 5%。”Safari 的智能跟踪预防（适用于所有 Apple 平台，包括 macOS）以及建模转化都会造成影响。对平台 Safari 数据要格外审慎。
• “我们连简单的问题都无法回答。”埋点不足或抽象层不当。根据团队提出的问题审核事件列表，并补齐缺口。
• “两位分析师算出的 MAU 不同。”身份关联方式不同。选择一个规范的身份层，并要求所有人都基于它查询。
• “数字与上一季度不同，却找不到原因。”底层架构发生变化，却没有版本控制。仪表板悄然失效，直到差距变大才有人发现。

详见 references/common-failures.md。

---

框架：值得信赖的产品分析需考虑的 12 个方面

设计或审核产品分析时，请逐一检查以下 12 个方面。任何一项被跳过，都可能导致团队最终得到无人信任的数据。

1. 事件分类体系。 使用过去时、对象-动作结构，细致但不冗余。动词是事件；状态是属性。
2. 属性设计。 区分事件级和用户级属性。严格管理类型。所有时间戳均使用 ISO 8601。
3. 命名规范。 选定一种并严格执行。默认采用 snake_case。
4. 架构版本控制。 区分新增变更与破坏性变更。过渡期间使用 _v2 后缀。在代码中定义数据契约。
5. 身份关联。 覆盖从匿名到已验证身份、跨设备和跨工具的关联。使用一个规范的身份层。
6. 漏斗设计。 以高意向事件为锚点。记录时间窗口。不要将自动触发的事件用作步骤。
7. 群组定义。 可复用、有版本控制、公平可比。在代码中定义，或保存在工具中。
8. 留存衡量。 使用 N 日区间以提高稳定性。比较生命周期相同的群组。
9. 北极星指标。 反映用户价值，且难以刷高。设置一个 NSM、三到五个输入指标、五到十个健康指标。
10. 仪表板维护。 明确指标定义、数据来源、负责人和刷新频率。弃用过时的仪表板。
11. 埋点债务。 每个 PR 都包含埋点。每季度审核一次。
12. 单一可信数据源。 董事会指标以数据仓库为准；正在进行的优化以工具为准。两者不一致时进行核对。

该框架的产出是一份跟踪计划：包含事件及其属性、规范的用户身份、命名的群组、命名的漏斗、留存衡量方式、命名的 NSM，以及仪表板负责人。计划保存在代码中，并像其他产品规范一样接受评审。

---

如果所需数据不可用

此技能的输出依赖于其自身无法生成的数据、测量结果或工具结果。如果所需输入、工具或数据源不可用或无法验证，合规的输出就是在交付内容中说明缺口：需要什么、实际获取或验证了什么，以及输出中的哪些部分受到影响。绝不允许为了完成交付内容而伪造、估算或插算所需数值。明确说明缺口就是完整的答复。

---

参考文件

• references/event-taxonomy-template.md - 典型 SaaS 的标准事件规范：账户、用户、激活、参与、转化、留存事件及其必需属性。
• references/property-design-patterns.md - 事件级与用户级属性模式。类型约束。示例：product_viewed 的正确与错误用法。
• references/naming-convention-reference.md - 完整风格指南。snake_case、过去时、对象-动作。布尔值前缀。金额以美分为单位。时间戳使用 _at 后缀。正反示例对照。
• references/schema-versioning-patterns.md - 兼容性变更与破坏性变更。_v2 后缀模式。TypeScript 中的数据契约。CI lint 模式。
• references/funnel-design-templates.md - 激活、转化、参与、功能采用漏斗。时间窗口、锚点事件、流失解读。
• references/cohort-definition-patterns.md - 获客、行为、属性、组合队列。SQL 示例及特定工具的示例。
• references/north-star-metric-selection.md - NSM 规则及各类产品的示例。反模式。更改 NSM 时的迁移模式。
• references/instrumentation-audit-checklist.md - 季度审计指南：架构审查、数据量合理性检查、仪表板新鲜度、负责人审计、弃用候选项。
• references/common-failures.md - 十二种失败模式，包含症状、根本原因、修复方法和预防措施。

---

结语：拿不准时，少埋点

大多数产品分析配置都是埋点过多，而非过少。追踪每次按钮点击会制造噪声，淹没有效信号。说“我们不需要追踪这个”比说“先追踪再说”更难。默认选择少埋点。

缺少的数据以后可以补上。过度收集的数据却会永远带来成本：影响仪表板性能，增加架构复杂度，降低信噪比。发布三十个设计精良的事件和一小组命名队列的团队，胜过发布两百个事件却毫无队列规范的团队。

团队对是否添加某个事件意见不一时，问题不该是“这可能有用吗？”，而应是“这个事件将为哪项具体决策提供信息，这项决策是否值得付出埋点成本？”如果答案是“我们可能会想知道”，那么答案就是不值得。