Vitals API V2概述
您可以使用Vitals API V2获取Fire TV和Fire平板电脑应用的运行状况指标和性能指标。应用运行状况指标包括崩溃率、应用无响应 (ANR) 率以及低内存终止 (LMK) 率。性能指标包括应用启动时间、就绪时间、慢启动率、丢帧率和慢渲染率。
该API将相关指标归入指标集。指标集中的所有指标具有相同的新鲜度。您可以一起查询指标集的所有指标。每个指标集都有维度，例如countryCode。您可以按维度的值筛选结果。您还可以按维度获取结果的细分。
Vitals API的版本2 (V2) 与版本1 (V1) 在以下方面有所不同：
- 每个路径都以版本开头，即
/v2/。 - 时间值为ISO 8601 UTC格式字符串，例如
2026-08-18T14:00:00Z。 - 指标值为JSON数字。
- 所有操作都使用同一种错误格式。
亚马逊继续支持V1。使用V2进行新的集成。将现有集成迁移到V2。有关必须进行的更改，请参阅从V1迁移。
Vitals API的使用受程序材料许可协议的约束。
先决条件
在发送请求之前，您需要以下各项：
- 具有管理员级别凭证的亚马逊开发者账户
- 关联到报告API的安全配置文件。要创建安全配置文件，请转到D开发者控制台中的“我的设置”>“API访问”。
- 安全配置文件的“Web设置”选项卡中显示的客户端ID和客户端密钥
- LWA范围
adx_reporting::appstore:marketer - 应用的程序包名称，例如
com.example.myapp。您的开发者账户必须拥有该应用。
工作方式
亚马逊从运行您应用的Fire TV和Fire平板电脑设备上收集崩溃报告和性能数据。使用这些指标来发现趋势，并比较应用版本、设备型号和国家/地区。这些计数为近似值，而非精确总数。亚马逊按每个UTC日和每个UTC小时计算指标。在本页面和Vitals API V2参考页面上，汇总时段为DAILY（按日）或HOURLY（按小时）值。一个时段是指DAILY查询中的一天或HOURLY查询中的一小时。
- 使用
DAILY汇总时段时，每个UTC日会得到一行。某天的数据通常可在次日（T-1天）获取。 - 使用
HOURLY汇总时段时，每个UTC小时会得到一行。某小时的数据通常在该小时开始后2–3小时（T-2小时）可用。使用HOURLY数据可在发布应用版本后不久发现新问题。
新鲜度
除issuesMetricSet外，每个指标集都有一个检查新鲜度操作 (GET)。它返回亚马逊针对每个可用汇总时段处理的最新时段。
issuesMetricSet没有检查新鲜度操作。对于CRASH问题，请使用crashMetricSet的新鲜度值。对于ANR问题，请使用anrMetricSet的新鲜度值。API按errorEventCount对问题进行排序，最高值在前。
| 汇总时段 | 通常延迟 | 近期查询窗口 |
|---|---|---|
DAILY |
T-1天 | 最近30个UTC日期 |
HOURLY |
T-2小时 | 最近15个UTC日期 |
新鲜度值为最新已处理时段的开始时间。例如，2026-08-18T00:00:00Z表示亚马逊已处理8月18日的DAILY数据。
将查询的结束时间设置为等于或早于新鲜度值。新鲜度并不表示您的应用在该时段是否有数据。设备可能会延迟发送数据，因此近期值可能会发生变化。再次查询近期时段以获取最新值。
数据查询
使用查询指标 (POST) 从指标集获取数据。指定汇总时段和时间范围。您也可以指定：
- 指标： 要返回的指标。如果省略它们，API会返回支持该汇总时段的所有指标。
- 维度： 用于细分的维度，例如
versionCode。 - 筛选条件： 要包含的维度值。筛选条件不会添加细分。筛选条件可以使用不在
dimensions中的维度。
不使用dimensions时，每个有数据的时段会得到一行。使用dimensions时，每个维度值与有数据时段的组合会得到一行。API会省略没有数据的时段。指标值仍可能为null。
使用格式为YYYY-MM-DDThh:mm:ssZ的UTC时间值。时间范围包含startTime和endTime所在的时段。
要获取高频崩溃或ANR问题，请使用Query Issues (issuesMetricSet)。
所有操作共享一个比率限制。有关更多信息，请参阅比率限制、重试和最佳实践。
可用指标集
下表列出了所有可用指标集及其支持的指标。
28d的指标外，所有指标都支持DAILY和HOURLY。这些指标仅支持DAILY。查询问题请求没有metrics字段。API会为每个问题返回issuesMetricSet的两个指标。| 指标集 | 指标 |
|---|---|
crashMetricSet |
crashRate（比率）： 发生崩溃的活跃设备占比 crashRate7dUserWeighted（比率）：7日崩溃率，按活跃设备加权 crashRate28dUserWeighted（比率）：28日崩溃率，按活跃设备加权 userPerceivedCrashRate（比率）： 发生前台崩溃的活跃设备占比 userPerceivedCrashRate7dUserWeighted（比率）：7日前台崩溃率 userPerceivedCrashRate28dUserWeighted（比率）：28日前台崩溃率 distinctDevices（计数）： 活跃设备的大致数量 crashCount（计数）： 崩溃事件总数 |
anrMetricSet |
anrRate（比率）： 发生ANR事件的活跃设备占比 anrRate7dUserWeighted（比率）：7日ANR率，按活跃设备加权 anrRate28dUserWeighted（比率）：28日ANR率，按活跃设备加权 userPerceivedAnrRate（比率）： 发生前台ANR事件的活跃设备占比 userPerceivedAnrRate7dUserWeighted（比率）：7日前台ANR率 userPerceivedAnrRate28dUserWeighted（比率）：28日前台ANR率 distinctDevices（计数）： 活跃设备的大致数量 anrCount（计数）： ANR事件总数 |
lmkMetricSet |
lmkRate（比率）： 发生LMK事件的活跃设备占比 lmkRate7dUserWeighted（比率）：7日LMK率，按活跃设备加权 lmkRate28dUserWeighted（比率）：28日LMK率，按活跃设备加权 userPerceivedLmkRate（比率）： 发生前台LMK事件的活跃设备占比 userPerceivedLmkRate7dUserWeighted（比率）：7日前台LMK率 userPerceivedLmkRate28dUserWeighted（比率）：28日前台LMK率 distinctDevices（计数）： 活跃设备的大致数量 lmkCount（计数）： LMK事件总数 |
issuesMetricSet |
errorEventCount（计数）： 该问题的崩溃或ANR事件总数 affectedDeviceCount（计数）： 受影响的不重复设备数 |
appLatencyMetricSet |
coldStartAppLaunchTime（时长）： 冷启动启动后到首个应用窗口出现的时间 warmStartAppLaunchTime（时长）： 热启动后到首个应用窗口出现的时间 |
readyToUseMetricSet |
coldStartReadyToUseTime（时长）： 冷启动后直到应用完全绘制完成的时间 warmStartReadyToUseTime（时长）： 热启动后直到应用完全绘制完成的时间 |
slowStartRateMetricSet |
slowStartRate（比率）： 按启动类型划分的发生慢启动的设备占比 slowStartRate7dDeviceWeighted（比率）：7日慢启动率，按设备加权 slowStartRate28dDeviceWeighted（比率）：28日慢启动率，按设备加权 distinctDevices（计数）： 所选启动类型的设备大致数量 |
fluidityMetricSet |
frameDropRate（比率）： 已丢弃的已渲染用户界面帧占比。此指标不包含媒体播放帧。 slowRenderingRate（比率）： 丢帧率超过25%的设备占比 slowRenderingRate7dDeviceWeighted（比率）：7日慢渲染率，按设备加权 slowRenderingRate28dDeviceWeighted（比率）：28日慢渲染率，按设备加权 distinctDevices（计数）： 发送帧数据的设备数量 |
就绪指标需要来自您应用的信号。
- 在FireOS上，当应用完全绘制完成时调用
Activity.reportFullyDrawn()。请参阅缩短应用启动时间。 - 在VegaOS上，使用
@amazon-devices/kepler-performance-api中的useReportFullyDrawn()。主屏幕和初始数据准备就绪后，调用返回的回调。当应用从后台返回并恢复响应后，再次调用该回调。请参阅衡量应用KPI。
指标值
比率是0到1之间的JSON数字。计数是整数。时长以毫秒为单位。每个时长指标包含三个统计数据： Average、P90 和 P95。百分位数值是近似值。null值不是0。
distinctDevices是近似值，在每个指标集中具有不同的含义。不要跨行或跨时段对其值进行求和。对于应用范围内的比率，在查询时不使用筛选条件或维度。
不要将不同行的比率相加。要获取多个维度值的比率，请使用不包含dimensions的filter。
维度
所有指标集均支持下表中的前六个维度。只有slowStartRateMetricSet支持startType。它要求在dimensions中包含startType。您可以将每个维度用于细分和筛选条件。
| 维度 | 类型 | 描述 | 值 |
|---|---|---|---|
versionCode |
字符串 | 设备记录数据时您的应用版本代码 | 例如151 |
countryCode |
字符串 | 大写两位ISO 3166-1 alpha-2国家代码 | 例如US |
deviceModel |
字符串 | 设备型号代号 | 例如AFTSS |
deviceType |
字符串 | 设备系列 | FIRE_TV、FIRE_TABLET或OTHER |
deviceOs |
字符串 | 设备的操作系统 | FIRE_OS或VEGA_OS |
osVersion |
字符串 | 操作系统的版本 | 例如PS7713/5443 |
startType |
字符串 | 应用启动类型 | COLD或WARM |
相关主题
- Vitals API V2参考： 先决条件、身份验证、API终结点、代码示例、错误处理和最佳实践
- 报告API： 销售、收益和订阅报表下载
- “应用运行状况洞察”控制面板： 相同指标的可视化仪表板
- 探索API： 链接到开发者控制台中的报告API浏览器
Last updated: 2026年10月13日
