01 快速开始
整个流程只有四步,后面每端接入的细节在各自的章节里。
- 登录或注册:登录页支持自助注册(服务端允许时),注册出来默认是可创建应用的账号。
- 新建应用:顶栏右侧「新建应用」,填个名字即可,系统会给一个
app_id。 - 接入 SDK:进控制台的「应用管理」页复制
app_id,再按应用端看 03–05 节对应的步骤。 - 回来看数据:「实时数据」页通常几秒内就能看到自己刚触发的页面浏览。
platform 属性区分来源即可。
02 账号与权限
账号不再区分角色:能看哪些应用、能不能写,全部由应用授权决定。
注册后即可在「应用管理」里创建自己的应用,创建时自动获得该应用的可写授权,不用等管理员分配。
首次引导创建的超级管理员默认可见全部应用,并负责账号管理与授权;普通成员只看得到自己创建的、以及被授权的应用。
授权粒度是按应用。一个应用都没有时会落到「先建一个应用」引导页,自己建一个就能开始用,不是登录失败。
没有写权限时所有写按钮都会隐藏——界面隐藏只是避免点到必然失败的入口,真正的拦截在接口层,绕过前端也写不进去。
03 Web 端接入
一行式接入(推荐)
把 app_id 写进 id 属性,SDK 加载后会读标签自己初始化,不需要额外写 JS:
<script id="你的 app_id"
src="//istats.denghb.com/istats.js" async></script>
加载即开始采集,默认全开:页面浏览、点击、性能、离开、JS 错误。
手动初始化(需要自定义配置时)
不带 id 属性即不自动初始化,由业务自己调:
<script src="https://istats.denghb.com/istats.js"></script>
<script>
Istats.init({
appId: 'app_xxx',
// host 不写默认 https://istats.denghb.com;换域名才需要显式传
autoPageView: true, // 含 SPA 的 pushState / hashchange
autoClick: true, // 只采集带 data-istats 的元素
autoError: true // 自动捕获 JS 错误 / Promise 异常 / 资源加载失败
});
Istats.identify('user_10086'); // 登录后绑定,UV 按此去重
Istats.track('pay_success', { amount: 199 }); // 自定义事件
Istats.captureException(err, { biz: 'checkout' }); // 手动上报异常
</script>
<meta name="app-version" content="1.2.3">
就自动带上,没有就留空;也可以显式传 appVersion。
identify(userId) 会把登录前设备 id 的历史事件归并到该用户;
Web / Flutter / 服务端用同一个 userId,就能串成同一个人。
自动采集的事件
| 事件名 | 触发时机 | 关键属性 |
|---|---|---|
$page_view | 页面加载与 SPA 路由切换 | 页面路径、来源、UTM |
$click | 点击带 data-istats 的元素 | 元素选择器、坐标、滚动位置 |
$page_leave | 离开页面(停留 < 300ms 不报) | dwell_ms、scroll_pct |
$perf | 页面加载完成 | TTFB、DCL、LCP、CLS、FID、DOM 节点数 |
$exception | JS 错误 / Promise 异常 / 资源失败 | 类型、消息、堆栈 |
data-istats 的元素,避免把页面上的每个按钮都染成一条事件。
给按钮加上 data-istats="checkout_click" 就会以该名字上报。
04 Flutter 端接入
在 runApp 之前 init 一次,页面切换交给 NavigatorObserver:
void main() {
WidgetsFlutterBinding.ensureInitialized();
Istats.init(
appId: 'demo_app',
// host 默认 https://istats.denghb.com,换域名才要写
// appVersion 可选:传 PackageInfo.version(package_info_plus)就能按版本切开
);
runApp(const MyApp());
}
MaterialApp(
navigatorObservers: [IstatsNavigatorObserver()], // 自动上报页面切换
...
)
Flutter 端会自动带上设备信息:平台、系统版本、设备型号与类型、屏幕尺寸、时区、CPU 核数。
appVersion 要业务自己传:
appVersion: (await PackageInfo.fromPlatform()).version(package_info_plus)。
不传就留空,不影响其它指标。
05 Java 服务端接入
agent 方式(零代码)
下载 istats-agent.jar 由当前 iStats 服务直接提供;也可以按下方 Maven 命令自行构建。
把 agent jar 挂到启动参数上,业务代码一行都不用改:
java -javaagent:istats-agent.jar=app_id=demo_app \
-jar your-app.jar
也认环境变量(ISTATS_APP_ID / ISTATS_AGENT_HOST /
ISTATS_APP_VERSION)。host 默认 https://istats.denghb.com,
换域名部署时才需要 host=...。
启动日志会有一行 [istats-agent] 已启动(premain) 确认接管成功。
| 自动采集 | 织入点 |
|---|---|
| HTTP 请求与耗时 | HttpServlet#service |
| 慢 SQL 与耗时 | JDBC execute* |
| 外部调用耗时 | RestTemplate / OkHttp / AsyncHttpClient |
| 未捕获异常 | 全局异常处理器 |
| 注解方法 | @IstatsTrack |
注解埋点
@IstatsTrack("order_submit")
public void submit(Order order) { ... }
侵入式 API
IstatsServer.init(new IstatsServer.Config().appId("demo_app"));
IstatsServer.track("pay_success", Props.of("amount", 199));
host 默认 https://istats.denghb.com;应用版本不传时,SDK 会从
jar 的 MANIFEST(Implementation-Version)里自己取。
两种方式可以共存;agent 已接管时,代码里的 init 会被忽略并打一行提示。
06 六个视图怎么用
左边的菜单会跟着当前应用的「平台服务」走:Java 服务端应用不显示「会话分析」, 因为它没有页面,入口页 / 出口页 / 页数这几列永远是空的。
数据概览
五个 KPI 看整体水位:事件量、活跃用户、会话数、页面浏览、新增用户;右边那张卡是跳出率、 人均事件数、平均会话时长。下面是趋势图、Top 事件与热门页面。时间范围切 1 / 7 / 30 天。
http_request 事件数)、
错误率(只算 5xx,4xx 是调用方问题不计入)、人均事件数;「页面浏览」标签与「热门页面」卡不再出现。事件分析
左边是事件清单(带自动/自定义标记、触发次数、影响用户数、最近触发时间),点一条看右侧详情: 趋势、页面分布、属性分布。属性分布能直接回答「哪个版本、哪个城市、哪个渠道」这类问题。
异常监控
按「类型 + 消息」聚合成指纹,一行一个错误种类:出现次数、影响用户数、首次与最近时间, 点开看最新一条堆栈样本。同一个错误只占一行,不会被刷屏。
实时数据
最近 30 分钟的事件流,5 秒刷新一次,每行可以展开看完整属性(含设备、系统、浏览器、IP、时区)。 排查「上报到底有没有到」时看这里最快。
会话分析
一分钟内多个事件会归到同一个会话。列表给每个会话的进出页面、事件数、页面数、时长、是否跳出; 点一行展开时间线,能看到每次跳转的间隔。跳出率高的时候,先看这里是从哪一步走的。
漏斗分析
最多 8 步,按同一会话内的先后顺序判定,给出每步人数、相对首步与上一步的转化率、流失量。
步骤可以按事件名加属性条件,比如「$page_view 且 page=/checkout」。
留存分析
以首次触发某个事件的那天为分组,看之后第 1 / 3 / 7 / 14 / 30 天的回访比例。
选一个能代表「真正用起来」的事件(比如 pay_success),比拿登录当留存更有意义。
07 阈值告警
一条规则 = 应用 + 事件 + 字段条件 + 阈值 + 通知渠道。命中就把当时的实际值发出去。
- 选事件与字段(字段来自该应用上报过的属性,没数据时字段列表是空的)。
- 选比较符(大于 / 小于 / 等于),填阈值。
- 选通知渠道:邮件或群机器人。渠道没配置时规则可以保存,但发送会落到
dry_run。 - 保存后可以「测试发送」,只发一次不落业务数据,用来验证渠道通不通。
| 状态 | 含义 |
|---|---|
sent | 已发送成功 |
dry_run | 渠道未配置,只记录未发送 |
failed | 发送失败(凭据、网络或接收方拒收) |
dry_run 观察几轮再开渠道。
08 指标口径
数字对不上时,先对照这四条:
| 指标 | 口径 |
|---|---|
| 「日」 | 按 Asia/Shanghai 切分,跨时区访客归到同一天。 |
| PV | 只统计 $page_view 与 $screen_view,自定义事件不计入 PV。 |
| UV | COUNT(DISTINCT distinct_id);调过 identify 是用户 ID,否则是设备 ID。 |
| 会话 | 30 分钟静默即切新会话;跳出率 = 只有 1 个页面的会话占比。 |
identify。
09 常见问题
接入后实时数据里看不到事件
- 确认标签上是
id="app_id",值就是控制台里那串 app_id,不是应用名。 - 上报是加密的,服务端拒收明文。如果自己改过 SDK 或中间层改写了请求体,会被直接拒掉。
- 用浏览器 Network 面板看
/collect的状态码:2xx 说明到了,4xx 看响应里的原因。
登录提示验证码错误
验证码是一次性的,提交失败后那张就作废了,必须点图换一张再提交。验证码校验在密码校验之前,所以「账号不存在」和「密码错误」的提示是一样的——这是为了避免账号被枚举。
UV 比预期高很多
大概率是没调 identify。未登录用户按设备 ID 去重,换设备、清缓存都会产生新的 UV。
会话数比事件数还多
会话按 30 分钟静默切分。低频上报(比如只在关键操作时上报)会导致每次上报都开一个新会话。这类场景建议直接看事件量,不要看会话指标。
看不到「账号与授权」
这个入口只对超级管理员显示;普通成员不需要它,也能创建并管理自己的应用。