@arms/rum-miniapp

@arms/rum-miniapp

阿里云用户体验监控小程序 SDK。支持微信 / 支付宝 / 百度 / 字节 / 快手 / 钉钉 / 京东等主流小程序平台，兼容 Taro / Uniapp 跨端框架。覆盖页面 PV、性能（含启动与渲染性能）、JS 异常、API（含 SSE 流式接口）、用户行为、页面卡顿等监控数据，并支持分布式链路追踪。

核心特性

• 多平台覆盖：微信 / 支付宝 / 百度 / 字节 / 快手 / 钉钉 / 京东小程序，以及 Taro / Uniapp 跨端框架
• 零配置即用：一次 init() 后默认启用 PV / 性能 / 异常 / API / 用户行为 / 卡顿 等采集器
• API 监控全覆盖：
  • 劫持 request / httpRequest 全局网络请求，自动产出 type='api' 资源事件
  • SSE 流式接口（微信小程序）独立子采集器，输出 time_to_first_token / inter_token_latency_avg / inter_token_latency_max / message_count 等指标
  • evaluateApi 回调把请求/响应内容写入 snapshots，SDK 自动裁剪至 5KB
• 卡顿监控：通过 setUpdatePerformanceListener 检测 setData 渲染阻塞，精确定位卡顿页面与数据路径
• 分布式链路追踪：内置 tracing 配置，支持 W3C tracecontext / B3 / B3 multi / Jaeger / SkyWalking sw8 协议
• 远程配置：支持云监控控制台下发配置，动态调整采样率、采集器开关、过滤规则

安装

npm install @arms/rum-miniapp

依赖	版本要求	说明
小程序平台	微信 / 支付宝 / 百度 / 字节 / 快手 / 钉钉 / 京东	SSE 监控仅微信（基础库 >= 2.20.2）支持
@babel/runtime	^7.24.5	peerDependency，由业务侧安装

快速开始

第一步：在小程序入口尽早初始化

init() 务必在业务发起任何网络请求之前调用——SDK 通过代理 request / httpRequest 实现 API 采集，初始化之前发出的请求采不到。

// app.ts
import ArmsRum from '@arms/rum-miniapp';

ArmsRum.init({
  pid: '<your-pid>',
  endpoint: '<your-endpoint>',
  env: 'prod',
  version: '1.0.0',
});

第二步：设置安全域名

将 endpoint 地址添加到小程序服务器域名白名单中（如微信「开发管理 > 开发设置 > 服务器域名 > request 合法域名」）。

第三步：（可选）验证数据上报

ArmsRum.init({
  pid: '<your-pid>',
  endpoint: '<your-endpoint>',
  beforeReport(bundle) {
    console.log('[RUM]', bundle);
    return bundle;
  },
});

配置项

init() 接收 IMiniappConfig 配置对象。下表只列出常用字段，完整版见 docs/SDK配置参考.md。

基础配置

字段	类型	必填	默认值	说明
pid	string	是	—	应用 ID
endpoint	string	是	—	ARMS 数据上报地址
enable	boolean	否	true	关闭后所有采集器与上报均不工作
env	'prod' | 'gray' | 'pre' | 'daily' | 'local'	否	'prod'	应用环境标识
version	string	否	—	应用版本号
user	object	否	—	用户信息（name / tags）

采集器开关（collectors）

ArmsRum.init({
  pid: '<your-pid>',
  endpoint: '<your-endpoint>',
  collectors: {
    consoleError: false,             // 关闭 console.error 拦截
    longTask: true,                  // 卡顿监控
    api: {
      enable: true,
      filters: [/\.internal\.example\.com/],
      sse: { timeout: 30000 },       // SSE 流 30s 无消息判超时
    },
  },
});

采集器	默认	说明
jsError	true	未捕获异常 + 未处理 Promise 拒绝
consoleError	true	console.error 拦截上报
api	true	网络请求监控（含 SSE）
action	true	用户行为（tap 事件）
longTask	true	页面卡顿（setData 渲染阻塞）
perf	true	页面性能指标

链路追踪（tracing）

ArmsRum.init({
  pid: '<your-pid>',
  endpoint: '<your-endpoint>',
  tracing: {
    enable: true,
    sample: 10,
    propagatorTypes: ['tracecontext', 'b3'],
    allowedUrls: [/^https:\/\/api\.example\.com/],
  },
});

运行时 API

import ArmsRum from '@arms/rum-miniapp';

// 修改单个字段
ArmsRum.setConfig('enable', false);

// 批量修改
ArmsRum.setConfig({ env: 'staging', version: '1.1.0' });

// 读取当前完整配置
const config = ArmsRum.getConfig();

// 获取某个采集器实例
const apiCollector = ArmsRum.getCollector('api-collector');

// 自定义事件上报
ArmsRum.sendCustom({
  type: 'business-event',
  name: 'order-submit',
});

注意事项

1. init() 务必尽早执行：SDK 通过代理 request / httpRequest 实现 API 采集，初始化之前发出的请求采不到。
2. 构建 npm：安装后需在小程序开发工具中执行构建 npm。
3. 安全域名必须配置：未添加 endpoint 到域名白名单会导致上报请求被拦截。
4. evaluateApi 内禁止同步阻塞：回调如抛错会被静默捕获回退到原始事件。
5. tracing.allowedUrls 必须显式声明：未配置时不会注入追踪头。
6. SSE 监控平台限制：仅微信小程序（基础库 >= 2.20.2）支持，其他平台静默降级为普通 API 监控。
7. 卡顿监控依赖基础库能力：低版本不支持 setUpdatePerformanceListener 时自动跳过。