@arms/rum-uniapp

阿里云 ARMS 用户体验监控 uni-app SDK。覆盖 uni-app 应用在 App 端（iOS / Android）、小程序端、H5 端的页面 PV、API 请求、JS 异常、用户交互等监控数据，并支持分布式链路追踪与 SDK 自监控。

核心特性

• 多端统一采集：一套 SDK 覆盖 uni-app App 端、小程序端、H5 端，无需分别接入
• PV 自动追踪：通过 uni.addInterceptor 拦截 navigateTo / redirectTo / switchTab 路由切换，自动产出页面 PV 事件
• API 请求监控：拦截 uni.request，采集请求 URL、方法、状态码、耗时、响应大小等指标
• 异常捕获：JS 错误（global error）、未处理 Promise 拒绝、uni.onError、Vue 组件错误（errorHandler / onErrorCaptured）、console.error 拦截
• 用户行为采集：通过 Vue mixin 拦截组件 methods，捕获 tap / click 交互事件，300ms 去重合并
• 会话管理：基于 uni storage 的会话跟踪，支持采样率、最大持续时间、无活动超时配置
• 自监控：SDK 内部运行状态监控，protobuf 编码独立上报，帮助快速定位兼容性问题
• 分布式链路追踪：支持 W3C tracecontext / B3 / B3 multi / Jaeger / SkyWalking sw8 协议，按 allowedUrls 白名单注入追踪头

安装

仅支持 NPM 方式接入。uni-app 需在构建时集成 SDK，不提供 CDN 接入。

npm install @arms/rum-uniapp

| 依赖 | 版本要求 | 说明 | |------|----------|------| | @arms/rum-core | ^0.1.7 | 核心监控能力（自动安装） | | Vue | ^2.6.x 或 ^3.x | uni-app 框架依赖，由业务侧提供 | | uni-app | ^2.x 或 ^3.x | 跨端框架运行时 |

快速接入

// main.js
import armsRum from '@arms/rum-uniapp';
import Vue from 'vue';   // Vue 2 项目
// import { createSSRApp } from 'vue'; // Vue 3 项目

armsRum.init({
  endpoint: '<your-endpoint>',
  pid: '<your-pid>',
  env: 'prod',
  version: '1.0.0',
  vue: Vue,   // Vue 2 传入构造函数；Vue 3 传入 createApp() 返回的 app 实例
});

完整接入步骤见 docs/接入uni-app应用.md。

配置项

init() 接收 IUniConfig 配置对象（继承自 core 的 IConfiguration）。下表只列出常用字段，完整版见 docs/SDK配置参考.md。

基础配置

| 字段 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | endpoint | string | 是 | — | ARMS 数据上报地址 | | pid | string | 否 | — | 项目 ID（兼容旧版本，新接入推荐用 endpoint 自动识别） | | enable | boolean | 否 | true | 关闭后所有采集器与上报均不工作 | | env | 'prod' \| 'gray' \| 'pre' \| 'daily' \| 'local' | 否 | — | 应用环境标识 | | version | string | 否 | — | 应用版本号 | | app | object | 否 | — | 应用扩展信息（name / channel / framework 等） | | user | object | 否 | — | 用户信息（id / name / tags） |

uni-app 专属配置

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | vue | Vue | — | Vue 运行时实例：Vue 2 传入构造函数，Vue 3 传入 createApp() 返回的 app 实例。必填 | | parseViewName | (url: string) => string | — | 自定义页面 name 解析（默认取路由 path） | | parseResourceName | (url: string) => string | — | 自定义资源 name 解析（默认取 URL pathname） | | tracing | boolean \| ITracingOption | — | 分布式链路追踪配置 | | evaluateApi | (request, response, error?) => Promise<IApiBaseAttr> | — | 自定义 API 事件解析回调 |

采集器开关（collectors）

armsRum.init({
  endpoint: '<your-endpoint>',
  vue: Vue,
  collectors: {
    jsError: true,           // 异常监听（默认开启）
    consoleError: false,    // 关闭 console.error 拦截
    api: true,               // API 请求采集（默认开启）
    action: true,            // 用户行为采集（默认开启）
  },
});

| 采集器 | 默认 | 说明 | |--------|------|------| | jsError | true | JS 异常 + 未处理 Promise 拒绝 + uni.onError + Vue 组件错误 | | consoleError | true | console.error 拦截上报 | | api | true | uni.request 请求监控（type='api'） | | action | true | 用户 tap / click 交互事件 |

运行时 API

import armsRum from '@arms/rum-uniapp';

// 初始化 SDK
armsRum.init({
  endpoint: '<your-endpoint>',
  vue: Vue,
  env: 'prod',
  version: '1.0.0',
});

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

// 批量修改
armsRum.setConfig({ env: 'daily', version: '2.0.0' });

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

// 动态设置 Vue 实例（延迟初始化场景）
armsRum.setVue(app);   // Vue 3: createApp() 返回的 app 实例

// 获取 SDK 版本号
console.log(armsRum.version);

注意事项

1. vue 参数必须传入：行为采集依赖 Vue mixin 拦截组件 methods，不传 vue 则行为采集器无法工作。Vue 2 传入构造函数，Vue 3 传入 createApp() 返回的 app 实例。
2. 初始化时机尽早：SDK 通过 uni.addInterceptor 拦截 request 和路由跳转，初始化之前发出的请求和页面跳转采不到。建议在 main.js 最顶部调用 init()。
3. 上报地址要求：endpoint 为 ARMS 数据上报地址，需在阿里云云监控控制台创建应用后获取。
4. 小程序域名白名单：在微信 / 支付宝等小程序平台使用时，需将上报 endpoint 域名加入 request 合法域名白名单。
5. 会话存储使用 uni storage：SDK 通过 uni.getStorageSync / uni.setStorageSync 存储会话 ID 与用户 ID，确保运行环境支持 storage API。
6. App 端异常堆栈格式差异：App 端（iOS / Android 原生容器）uni.onError 回调参数为字符串，堆栈格式为 functionName@sourceURL:line:column（以 @ 分隔），与浏览器 V8 的 at functionName (sourceURL:line:column) 不同。SDK 已兼容两种格式。
7. 不支持的能力：本 SDK 不支持 CDN 接入、会话回放、白屏检测、Web Vitals、静态资源监控、长任务、SSE 流式接口监控。如需这些能力请在 Web & H5 端使用 @arms/rum-browser。