漏斗、路径与留存

三种查询，三种不同的身份。搞清楚某个数字统计的是哪一种，是这三者不互相打架的前提。

漏斗

漏斗统计的是有多少会话按顺序走到了每一步。

POST /api/v1/projects/{projectId}/analytics/funnels/query

{
  "from": "2026-09-01T00:00:00Z",
  "to": "2026-09-08T00:00:00Z",
  "windowSeconds": 3600,
  "dimension": "country",
  "steps": [
    { "kind": "page_view" },
    { "kind": "custom", "name": "cart_viewed" },
    { "kind": "custom", "name": "checkout_completed" }
  ]
}

语义

• 身份是会话，不是访客。 用户明天再来是另一个会话，漏斗从头开始算。
• 要求顺序，但不要求相邻。 各步的时间戳必须严格递增，中间夹杂其他事件不会打断漏斗。
• 时间窗覆盖整个漏斗，从第一步到最后一步，取值只能是 1800、3600 或 86400 秒。
• 步骤类型有 page_view、navigation、click、custom。只有 custom 需要填 name， 其余三种匹配该类型的所有事件——也就是说漏斗目前无法锚定到某个具体页面。 需要的话，用一个自定义事件来代替。

限制

限制项	取值
步骤数	2–5
时间范围	≤ 30 天
拆分维度返回值数	100，超过则返回基数错误
返回的会话样本	20 条，走得最深的排前面

这些样本是通往调查的桥梁：挑一个走到第 2 步就停下的会话点进去，看它接下来干了什么。

路径

路径展示的是会话最前面 N 个事件里最常见的组合，而不是任意两点之间的跳转。

• depth 2–5 个事件，topN 取 5 / 10 / 20，时间范围 ≤ 7 天
• 每一步的标签形如 page:<route>、navigation:<route>、click、event:<name>
• 没有传 Route 时，回退到归一化后的页面 URL
• 每个会话只取最前面 100 个事件参与计算，再按 depth 截断

因为它锚定在会话开头，所以路径回答的是「大家一进来先去哪」，不是「什么导致了转化」。 后者请用漏斗。

留存

按匿名访客 ID 做的周度同期群。

• 访客的同期群 = 他在所选时间范围内首次活跃的那个自然周（周一为起点），不是他真正的历史首访
• 某访客在第 n 周产生过任意 page_view 或自定义事件，即算作该周留存
• 默认 8 周

因为同期群是按查询范围划分的，放宽范围会让访客在同期群之间移动。跨次对比留存时， 请保证时间范围一致。

以上三种查询都受查询预算约束。