行为分析（Analytics）

行为分析回答”用户在产品里做了什么、在哪一步流失、还会不会回来”。接入方式只有一个动作：在端上调 Argus.track(name, properties) 上报埋点事件（Track Event），事件经统一上报链路 （HMAC 签名 → POST /v1/events → ClickHouse events_track）落库后，即可在 Console 与 MCP 工具中做 漏斗（Funnel）、留存（Retention）、同期群（Cohort）与维度对比分析——无预聚合管道，事件落库即可查。

核心概念

埋点事件（Track Event）

一条埋点事件包含：event_name（事件名）、user_id / anonymous_id / session_id（身份与会话）、 properties（自定义键值，字符串对字符串）、platform、app_version，以及渠道归因三元组 utm_source / utm_medium / utm_campaign。

事件名建议用小写下划线风格（如 sign_up、add_to_cart）并全端统一——signUp 与 sign_up 会被当成两个不同事件，直接让漏斗断裂。

用户识别（Identify）

• 登录后调用 Argus.identify(userId)，其后所有事件携带该 user_id。
• 漏斗 / 留存 / 同期群当前只统计带 user_id 的事件——匿名事件（仅有 anonymous_id）会出现在 事件明细和总量统计里，但不参与去重分析。匿名回退与身份缝合（identity stitching）为规划中能力。

渠道归因（UTM Attribution）

每条 track 事件可携带 utm_source / utm_medium / utm_campaign，之后漏斗、留存、同期群都能按 获客渠道过滤与对比。各端采集方式不同（详见下方接入矩阵）：Web 从落地页 URL 自动解析；移动端没有 URL，由 App 从 deep link / Google Play Install Referrer 等来源解析后调 setAttribution 设置。

漏斗（Funnel）

多步骤有序转化分析，基于 ClickHouse windowFunnel：

• 有序、非严格相邻：步骤必须按给定顺序发生，中间可以夹杂其他事件（Mixpanel / Amplitude 的标准语义）。
• 转化窗口：同一用户须在窗口内（默认 24 小时，可调）从第一步走到该步。
• 按用户去重：同一用户 24h 内完成 3 次全漏斗，对每步的贡献仍是 1。
• 单调不增：第 N 步用户数 ≥ 第 N+1 步（到达深层的人必然经过浅层）。
• 至少 2 个步骤，可叠加平台 / 版本 / UTM 维度过滤。

留存（Retention）与同期群（Cohort）

• day 0：每个用户在分析窗口内的首次活跃日。
• N 日留存率 = 在第 N 天偏移当天回访的去重用户数 ÷ day 0 用户数（exact day-N 口径）。
• 同期群矩阵：把用户按首次活跃日分组（粒度可选按天 / 按周 / 按月），每行一个 cohort、每列第 N 天 留存率——用于对比”某次发版 / 某个渠道之后进来的用户是否留得更差”。低流量项目建议切按周 / 按月， 每行样本更足。

维度（Dimensions)

可用的分析过滤维度为 platform、app_version、utm_source、utm_medium、utm_campaign 五个， 取值来自该项目近 N 天实际出现过的值（Console 的过滤输入框会自动补全）。

接入

平台矩阵

埋点是端上能力；5 个后端 SDK（Go / Node / Python / Java / Rust）不提供 track API，后端侧请用 日志 / Trace / Metric（见 后端 SDK 对照表 ）。

最小接入片段

import { Argus } from "@argus/sdk-web";
 
Argus.init({ dsn: "argus://...", userId: "user-123", appVersion: "1.0.0" });
 
Argus.track("signup");
Argus.track("add_to_cart", { sku: "ABC-123", price: "29.99" });
Argus.identify("user-456");

Argus.track("signup")
Argus.track("add_to_cart", properties: ["sku": "ABC-123", "price": "29.99"])
 
// 手动归因：从 deep link / 第三方归因 SDK 拿到 UTM 后尽早调用
Argus.setAttribution(utmSource: "google", utmMedium: "cpc", utmCampaign: "spring_sale")
 
// deep link 自动归因：把打开 App 的 URL 转给 SDK，自动解析 utm 并持久化
// SwiftUI:
.onOpenURL { url in Argus.handleAttributionURL(url) }

Argus.track("signup")
Argus.track("add_to_cart", mapOf("sku" to "ABC-123", "price" to "29.99"))
 
// 手动归因：解析到带 utm 的 deep link 后调用
Argus.setAttribution("google", "cpc", "spring_sale")
 
// 自动归因（opt-in）：从 Google Play Install Referrer 拿安装来源 utm
Argus.init(applicationContext, ArgusConfig.Builder(dsn)
    .captureInstallReferrer(true)
    .build())

Argus.track('signup');
Argus.track('add_to_cart', properties: {'sku': 'ABC-123'});
Argus.identify('user-456');
 
// 手动归因：App 解析到带 utm 的 deep link / 路由后设置
Argus.setAttribution(attr.utmSource,
    utmMedium: attr.utmMedium, utmCampaign: attr.utmCampaign);

Argus.track("purchase", { sku: "A1", price: "9.99" });
 
// 手动归因（可用 parseUtm 从 deep link query 串解析）
Argus.setAttribution({ utm_source: "google", utm_medium: "cpc", utm_campaign: "spring" });

Console 使用

进入 Console 左侧导航 Analytics 页（先在左上角选择项目），页面自上而下：

1. 事件总数 + 日趋势：近 14 天事件总量与逐日柱状趋势。
2. Top 事件名：近 14 天按量排序的事件名清单——先看这里确认埋点已生效、事件名拼写一致。
3. 漏斗分析：输入逗号分隔的有序事件名（至少 2 个，如 signup, activate, purchase），点”分析”。 每步显示去重用户数、相对上一步转化率、相对首步总转化率。可按平台（iOS / Android / Web / Flutter）、 版本（app_version）、渠道（utm_source）、媒介（utm_medium）、活动（utm_campaign）过滤， 过滤值有自动补全（取自该项目实际出现过的维度值）。
4. 留存分析：自动加载近 30 天 cohort 的 day 0–7 留存曲线，支持同一组维度过滤。
5. 留存矩阵（按 cohort）：行 = 首次活跃日 cohort（粒度可切按天 / 按周 / 按月），列 = day 0–7 留存率热力图。
6. 维度对比：选一个维度（平台 / 版本 / 渠道 / 媒介 / 活动），把它各个取值的留存曲线并排成热力图， 一眼看出”哪个渠道 / 平台 / 版本留存最好”（每次最多对比 8 个值）。
7. 最近事件：原始事件明细（时间 / 事件名 / 用户 / 平台 / 版本），支持按事件名搜索。

SDK API 速查

MCP 工具

在 Claude / Cursor 等 AI 客户端接入 Argus MCP Server 后，可用自然语言查行为数据。 工具名与参数以 services/mcp-server/src/tools/ 源码为准：

典型提问：“对比 iOS 与 Android 的 signup → purchase 漏斗”、“utm_source=google 的用户 7 日留存是多少”。

配额与计费

• 1 条 track 事件 = 1 个计费事件（event），计入项目事件量配额。
• 已识别用户（user_id 非空）计入计费 MAU。
• 超量行为与套餐细则见 套餐、配额与计费。

FAQ

漏斗 / 留存显示为 0，但最近事件里明明有数据？ 最常见的两个原因：① 事件没带 user_id（漏斗 / 留存按 user_id 去重，匿名事件不参与）； ② 漏斗步骤的事件名与实际上报不一致（精确匹配，注意大小写与下划线）。可先用 Console 的 “Top 事件名”或 MCP analytics.dimensions / track.recent 核对真实事件名。

事件上报后多久能查到？ 落库即可查。分析是查询时对 events_track 实时聚合，没有预计算延迟；离线缓存的事件按其 事件发生时间（event time）归入历史日，而非上报到达时间。

匿名用户会被算成两个人吗？ 未登录期间以 anonymous_id 标识、登录后以 user_id 标识，当前二者不会自动合并 （identity stitching 规划中）。总量类统计两者都计；去重类分析（漏斗 / 留存）只计 user_id。

properties 里能放数字做聚合吗？ 可以放（会以字符串存储），但当前查询层不做数值类型解释——避免依赖对 properties 的数值排序 / 范围过滤。数值属性类型系统为规划中能力。

“会话”是怎么切分的？ 当前各端 SDK 的 session_id 随进程生成，即”一次进程运行 ≈ 一个会话”；30 分钟无操作超时 / 前后台切换的行业标准会话切分为规划中口径（见指标字典 §A.1）。