# 数据分析

查看更新趋势、包体分布、版本健康度和设备明细，找到问题再决定是否扩大更新范围。

## 打开数据分析 {#analytics}

登录控制台，点击左侧**实时数据**。页面依次包含请求概览、包体分布、版本健康度、设备维度和遥测事件明细。

1. **应用**选择刚发布的应用，注意 Android、iOS 和 HarmonyOS 是不同应用。
2. **渠道**选择本次发布渠道；看整体时选全部渠道。
3. **窗口**先选最近 24 小时，确保包含发布时间。
4. 点击**刷新**，从请求概览往下查看。

下面截图来自 Pakta 实际控制台组件，使用演示数据，展示读数方法。

## 请求概览：更新进行到哪一步 {#events}

![请求概览：五类更新事件计数及趋势曲线，演示数据](/docs-media/analytics-overview.png)

| 页面指标 | 事件名 | 代表什么 |
| --- | --- | --- |
| 下载成功 | `download_success` | 更新文件已下载完成，尚不代表新版本启动成功 |
| 下载失败 | `download_fail` | 下载未成功，检查网络和下载地址 |
| Patch 失败 | `patch_fail` | 补丁或切换阶段出错；之后仍可能通过完整包成功更新 |
| 回滚 | `rollback` | 设备启动新版本异常后恢复到可用版本 |
| 启动成功 | `mark_success` | SDK 已确认新版本可用 |

趋势图把这些事件按时间绘成五条线。将鼠标移到图上查看对应时间点的数量；先看异常是不是从发布后开始，再下钻到具体版本。

同一台手机可能上报多条事件，所以这里的请求量不是新增用户数，也不是检查更新接口的全部访问量。下载成功与启动成功发生的时间也可能不同。

## 时间范围和曲线怎么看 {#trends}

- **窗口**支持最近 24 小时、72 小时、7 天，以及自定义起止时间；自定义范围最多 8 天，开始必须早于结束。
- **桶粒度**表示每个点汇总多少分钟的数据。选 5 分钟看短时异常，选 30 或 60 分钟看多天走势，也可以保持自动。
- **事件类型**选择“下载失败”时，图表强调该曲线，事件明细只显示相应类型。概览计数和版本健康度仍保留全部类型，方便对照。
- **刷新**重新读取当前条件下的数据。切换应用、渠道或时间后，重新确认筛选条件，避免把旧范围的观察结论套到新范围。

例如 14:00 发布后失败突然上升：先选包含 14:00 的两小时时间范围，将粒度设为 5 分钟，再看失败从哪个时间点开始。

## 包体分布：哪些版本还有人在用 {#package-distribution}

滚动到**包体分布**，在**热更包 / 原生包**之间切换：

| 维度 | 一行代表什么 | 适合回答的问题 |
| --- | --- | --- |
| 热更包 | 按更新 hash 区分的包 | 新更新是否开始收到设备上报？旧更新是否还在使用？ |
| 原生包 | 按原生版本号汇总 | 哪些安装包版本仍有活动，修复应覆盖哪些版本？ |

每行有请求量与占整体的比例，默认展示前 6 个包，超出的数量在列表末尾汇总。横条长度相对请求量最多的包展示，不要把横条长度直接当作全体用户覆盖率。

例如，原生版本 `1.0.0` 仍有大量记录，而新更新只发到了 `2.0.0`，那么 `1.0.0` 用户不会因这次发布获得修复。回到发布窗口核对目标，而不是继续增加 `2.0.0` 的比例。

## 版本健康度：是否继续扩大比例 {#version-health}

![版本健康度：按更新及原生版本对照下载失败率和回滚率，演示数据](/docs-media/analytics-health.png)

找到本次更新 hash 和原生版本所在行，对照上一稳定版本的数量与比率。

| 指标 | 计算方法 | 演示 |
| --- | --- | --- |
| 下载失败率 | 下载失败 ÷（下载成功 + 下载失败） | 20 ÷（980 + 20）= 2% |
| 回滚率 | 回滚 ÷（启动成功 + 回滚） | 5 ÷（945 + 5）≈ 0.5% |

分母为零时页面显示 0，不代表已经验证成功。样本太少时先增加测试和观察时间，不能凭“0%”直接全量。

1. 下载失败率升高：查明细中的网络、HTTP 或文件错误。
2. Patch 失败升高、最终下载成功：检查差分失败原因，同时确认完整包回退是否成功。
3. 回滚升高：停止扩大比例，核对新版本启动错误和健康确认逻辑。
4. 下载、启动成功持续出现且关键业务验证正常：按计划逐步增加比例。

## 设备维度：查一台手机 {#devices}

在**设备维度**中找到测试手机的设备标识。开发可通过 `getUpdateMetadata().uuid` 取得它。

1. 核对设备的 OS、五类事件次数、两项失败率、首次和最近上报时间。
2. 点击设备行，下方**遥测事件明细**只显示该设备记录；上方出现已选设备标签。
3. 按时间查看先下载、后启动确认，还是下载后回滚。
4. 再点该设备行或删除上方设备筛选标签，恢复全部设备。

每页显示 20 台设备，可用页码查看下一页。设备筛选联动事件明细，不会把整页概览改成单台设备数据。

## 遥测事件明细：找到失败原因 {#event-details}

明细包含时间、类型、设备、系统、包版本、构建信息和详情。先按“事件类型”缩小范围，再核对更新 hash 和发生时间。

| 看到的现象 | 继续检查 |
| --- | --- |
| 下载成功后没有启动成功 | App 是否完整重启，是否采用下次启动策略，是否完成 markSuccess |
| 同一设备出现回滚 | 对照问题更新 hash，查看启动错误；见[JS 报错监控](/docs/errors) |
| 多设备同一时间下载失败 | 下载域名和对象是否可访问、网络是否异常 |
| 找不到记录 | 清除类型/设备筛选，核对应用、渠道、时间和 SDK 上报设置 |

明细默认保留 7 天，实际以服务端保留配置为准。需要调查时及时记录时间、设备标识、原生版本与更新 hash。

## 完成一次发布验收 {#loop}

在测试手机确认新内容已经显示，再在数据页找到对应更新的下载和启动成功记录，最后检查关键业务页面。

确认正常后去[控制台调整比例](/docs/console#rollout)。发现问题时先[停止发布或恢复稳定版本](/docs/console#rollback)，保存事件证据再排查。

`disableTelemetry: true` 会关闭客户端相关事件上报。打开页面但没有数据时，先让开发确认此项未关闭，设备确实执行过 Release 更新流程并能连接服务端。