configuring-experiment-analytics

配置实验分析

此技能回答：分析中包含哪些用户？以及如何衡量影响？

曝光条件

曝光条件决定哪些用户会被计入实验分析。

曝光事件

有两种选择：

1. 默认曝光事件 — 当实验标志的默认曝光事件触发时，用户会被纳入分析：$feature_flag_called，或较新实验使用的 $experiment_exposure。具体使用哪个事件由服务器端确定——请从 experiment-get 中读取 resolved_exposure_event，不要自行假定是哪一个（这两个事件携带相同的属性）。如果是 $feature_flag_called，还要读取 $experiment_exposure（event IN ('$feature_flag_called', '$experiment_exposure')），并统计人数，而不是行数。这是标准做法——这意味着只有当用户在代码中实际遇到该功能标志时，才会被纳入分析。
2. 自定义曝光事件 — 当特定的自定义事件触发时，用户会被纳入分析。如果你想更精确地控制哪些用户进入分析（例如，仅纳入实际访问实验所在页面的用户），请使用此选项。

多变体处理

当用户接触到多个变体时（例如，由于标志变更或竞争条件）：

• 从分析中排除 — 将这些用户完全从分析中移除。数据更干净，但样本更小。
• 使用首次看到的变体 — 将用户分配到他们首次接触的变体。所有用户都会保留在分析中。请注意，“首次看到”可能会引入其他偏差，因为用户行为无法明确归因于单一变体，因此除非必要，否则不建议使用。

不均衡分流的偏差风险。“从分析中排除”与不均衡的变体分流搭配使用时可能引入偏差——多变体用户会被不对称地剔除，较小变体会损失更大比例的分配用户。如果这些用户的行为与其他用户不同，较小变体的指标就会产生偏差。

合适的缓解措施取决于实验状态：

• 尚未启动，或目前只向少数用户曝光 — 切换为均衡的变体分流，并使用整体发布百分比限制测试变体的曝光。这可以消除偏差并保留统计效力。请参阅 configuring-experiment-rollout。
• 正在运行且已有大量曝光的实验 — 在运行期间更改分流会重新分配用户的变体，这会损害用户体验和数据质量。请改为将此设置切换为“使用首次看到的变体”——这会使已分配的用户保留在原有变体中（不会重新分配），并消除不对称排除。

筛选测试账号

exposure_criteria.filterTestAccounts（默认值：true）— 将内部用户／测试用户排除在分析之外。

解析实验

更改指标需要实验 ID。如果用户通过名称或描述提及某个实验（例如“为结账测试添加指标”），请加载 finding-experiments 技能，在继续操作前将其解析为具体 ID。

指标

指标通过以下两种方式之一添加到实验，均使用 experiment-update：

• 内联指标 — 直接在实验上定义。通过 metrics 数组发送，该数组会替换整个内联指标列表，因此务必先通过 experiment-get 获取当前实验，以保留现有指标。
• 共享指标（已保存指标） — 可重复使用的指标对象，可附加到多个实验。通过 ID 使用 saved_metrics_ids 附加（此列表也会替换实验现有的已保存指标关联，因此请重新发送完整列表——参见步骤 1）。

**优先重复使用共享指标，而不是复制为内联指标。**只有在没有合适的现有共享指标时，才创建新的内联指标。

步骤 1：检查是否已有共享指标（必须执行——按定义匹配，而非按名称匹配）

在构建任何新的内联指标之前，必须检查项目中是否已有衡量相同内容的共享（已保存）指标，并复用它。复制已有的共享指标会导致衡量结果分散，这正是我们要避免的情况。

是否复用取决于指标的_定义_——事件或操作加指标类型——而不是名称。 已保存指标的命名遵循各团队自己的惯例，你无法猜出这些惯例，因此必须比较每个指标衡量的内容（其 query），而不是标题。

工作流程：

1. 先确定要构建什么。 在搜索之前，确定目标事件／操作和指标类型（mean / funnel / ratio / retention）——请参阅步骤 2，通过 read-data-schema 确认事件存在。只有明确具体事件／操作后，才能识别重复指标，因此应在确定事件之后、而非之前执行此检查。
2. 按事件搜索，然后比较每个候选项的 query。 调用 experiment-saved-metrics-list 并传入 ?event=<the event you're measuring>，查找引用该事件的指标——可以是直接匹配（EventsNode），也可以通过指标引用的任一操作的步骤事件匹配，因此按操作定义的指标也能通过其操作触发的事件找到。然后检查每个返回条目的 query（而不是 name／description）：如果某个已保存指标的 query 衡量的是相同事件或操作，且 metric_type 相同（并且 math 兼容），那么即使名称不同，也属于可复用的匹配项。
   • 按事件匹配，而不是按操作名称匹配。 按操作定义的指标可通过该操作触发的事件找到——传入该事件，而不是操作的标签。
   • 不要为此使用 search。 search 只匹配指标自身的 name／description／标签——不会匹配底层事件或操作——因此无法找到定义匹配项。只有在用户指定了要关联的某个已保存指标时，才使用 search（解析名称，而非匹配定义）。
3. 如果某个已保存指标与定义匹配——向用户确认匹配的名称／描述，然后关联该指标，而不是新建指标：
   • 调用 experiment-get，读取实验当前的 saved_metrics。
   • 调用 experiment-update，将 saved_metrics_ids 设置为完整的目标集合——它会替换现有的关联，因此要包含已关联的条目以及新条目。每个条目的结构为 { "id": <saved-metric id>, "metadata": { "type": "primary" } }——将 type 设为 "primary" 或 "secondary"。metadata 是可选项，默认为 primary。
   • 重建集合时留意 id： 刚读取的 saved_metrics 中，每个条目都有一个顶层 id（关联 id）和一个 saved_metric 字段（指标 id）。saved_metrics_ids 需要的是 saved_metric 的值，而不是关联 id——传入关联 id 会导致关联到错误的指标或验证失败。
   • 无需构建内联指标——共享指标已经包含其事件定义。
4. 如果指标库中没有衡量相同事件／操作和类型的指标——则构建内联指标（步骤 2 及后续步骤）。如果该内联指标很可能会在多个实验中复用，请提议通过 experiment-saved-metrics-create 将其创建为共享指标，然后按上述方式关联，以便后续实验复用。

步骤 2：发现可用事件（构建内联指标前的必需步骤）

在建议或构建任何新的内联指标之前，必须调用 read-data-schema，以查明项目中实际存在的事件。不要跳过此步骤。 不要根据你认为项目可能会追踪的内容来建议事件名称——只能使用已确认存在的事件。 （从步骤 1 附加现有的共享指标不需要执行此操作，因为其中已包含对应事件。）

即使在以下情况下，此步骤仍然适用：

• 用户提供了事件名称——查询以确认这些事件确实存在且拼写正确
• 用户询问“你建议使用哪些指标？”——先查询事件，再根据真实数据提出建议
• 上下文让某些事件看似显而易见——它们可能并不存在，或者名称有所不同

工作流：

1. 调用 read-data-schema 获取项目的事件
2. 根据实验假设向用户展示相关事件
3. 由用户选择用于指标的事件
4. 使用已确认的事件名称配置指标

合理的例外——allow_unknown_events: true： 仅当用户有意埋点尚未采集的事件时（例如，在代码变更上线前设置实验），才在 experiment-create / experiment-update 上传入此参数。请向用户确认这一点——切勿将其用作“事件查询未返回预期结果”的变通方法。

示例：

User: "Let's add some metrics for the checkout experiment"

WRONG: "I'd suggest using purchase_completed as the primary metric..."
  (hallucinated event name — never seen the project's actual events)

RIGHT: *calls read-data-schema* → "Here are the events in your project
  related to checkout: `checkout_step_completed`, `payment_processed`,
  `order_confirmed`. Which of these represents a successful checkout?"

步骤 3：选择指标类型

从 references/metric-templates.md 中的模板开始：它将常见请求（“收入增加”“用户回来”）映射到指标类型，以及与之搭配的默认设置（窗口单位、缩尾处理、目标）。

共有四种指标类型。每种的 kind 均为 "ExperimentMetric"：

metric_type	适用场景	必填字段
"mean"	计算每位用户某个数值属性的平均值（收入、会话时长、每位用户的页面浏览量）	source
"funnel"	从曝光到一个或多个有序操作的转化率	series（1 个或多个步骤）
"ratio"	一个事件相对于另一个事件的比率	numerator、denominator — 在一侧设置 math: "sum" + math_property 以聚合属性；筛选条件永远不会聚合
"retention"	曝光后用户是否会回来？	start_event、completion_event、retention_window_start、retention_window_end、retention_window_unit、start_handling

漏斗指标与隐式曝光步骤

漏斗指标会自动将实验的曝光事件作为 step_0 添加到最前面。 因此，series 中只有 1 个步骤的漏斗也是有效的 2 步漏斗：曝光 → 操作。 要衡量“曝光用户中有多大比例执行了 X？”，这就是正确的选择。

示例：

• “曝光用户中有多少比例到达了 /login？” → 包含 1 个步骤的漏斗（筛选到 /login 的 $pageview）
• “曝光用户中有多少比例完成了结账？” → 包含 1 个步骤的漏斗（checkout_completed）
• “曝光用户中有多少比例依次完成了购物车 → 结账 → 购买？” → 包含 3 个步骤的漏斗

同一事件的均值指标与漏斗指标

• 均值指标衡量每位用户的平均次数／数值（例如“每位用户的页面浏览量”“每位用户的收入”）。
• 漏斗指标衡量转化率（例如“曝光用户中完成购买的比例”）。

两者可以引用同一个事件，区别在于你关注的是次数／数值大小（均值指标），还是是否转化（漏斗指标）。

留存：起始事件与完成事件相同或不同

留存窗口从起始事件开始计算，因此，所选事件决定了衡量的内容： 起始事件不会被计作自身的完成事件（只有之后发生的不同事件才会计入），因此以下两种形式都有效：

• 起始事件与完成事件不同 → 转化型留存（“他们是否在窗口内执行了目标操作？”）。
• 起始事件与完成事件相同 → 重复留存（“他们是否再次触发了该事件？”）。From 0 会计算从同一时段起及之后发生的重复事件（包括当天的重复事件）；From ≥ 1 则要求之后发生事件。使用 start_handling: "first_seen"。用户说“<event> 的留存”时，通常指重复留存。

有关完整渲染后的 ExperimentMetric 架构（所有四种指标类型及每种类型的必填字段），以及最常见失败情形的错误／正确 JSON 对照（ratio 使用 is_set 筛选条件而不是 math: "sum" + math_property；retention 缺少 retention_window_start / start_handling），请参阅 references/metric-configuration.md。组装 ratio 或 retention 负载前请先阅读；必填字段以此为准。

步骤 4：主要指标与次要指标

• 主要指标 — 实验的核心成功标准，决定是否发布或结束。
• 次要指标 — 用于提供背景信息的补充测量指标。可用作护栏指标（例如，确保转化率提升不会导致错误率上升）。

解读结果

请参阅 references/interpreting-results.md，了解如何解读实验结果、统计显著性，以及何时发布或结束实验。

相关技能

• configuring-experiment-rollout — 发布方面：变体分流和流量百分比
• diagnosing-experiment-health — 结果存在偏差、为空或异常时使用
• analyzing-experiment-session-replays — 定性补充：观察各变体用户的实际行为