将Web应用接入ARMS用户体验监控_应用实时监控服务(ARMS)-阿里云帮助中心

ARMS用户体验监控针对Web & H5主要监控浏览器页面以及移动应用中的H5页面，通过页面内嵌JS脚本或NPM包的方式，采集应用站点运行过程中的性能指标，追踪异常问题，帮助您提升自身应用站点的用户体验。

重要

阿里云用户体验监控于2024年06月24日00:00:00（UTC+8）起正式商用，计费详情，请参见按量付费。如果您在使用中有任何问题，请联系用户体验监控答疑钉钉群（群号：67370002064）获取帮助。

创建监控应用

登录ARMS控制台。
在左侧导航栏选择用户体验监控> > 应用列表，并在顶部菜单栏选择目标地域。
在应用列表页面单击添加应用。
在创建应用面板单击Web & H5。
在接入Web & H5面板输入应用名称和描述，然后单击创建。
说明
应用名称唯一，不能与已创建的应用名称重复。
创建成功后，当前应用将会在STEP2区域自动生成对应的pid和endpoint地址。
在STEP2区域选择安装方式并安装探针SDK。
CDN同步加载
复制下方代码，并粘贴至HTML页面<body>中的第一行。
说明
请将以下代码中的pid和endpoint替换为当前应用对应的pid和endpoint地址。
```
<script>
  window.__rum = {
    pid: "your app id",
    endpoint: "your endpoint"
  };
</script>
<script type="text/javascript" src="https://sdk.rum.aliyuncs.com/v2/browser-sdk.js " crossorigin></script>
```
CDN异步加载
复制下方代码，并粘贴至HTML页面<body>中的第一行。
说明
请将以下代码中的pid和endpoint替换为当前应用对应的pid和endpoint地址。
```
<script>
  !(function(c,b,d,a){c[a]||(c[a]={});c[a]={
    pid: "your app id",
    endpoint: "your endpoint"
  };
  with(b)with(body)with(insertBefore(createElement("script"),firstChild))setAttribute("crossorigin","",src=d)
  })(window, document, "https://sdk.rum.aliyuncs.com/v2/browser-sdk.js ", "__rum");
</script>
```
npm包
1. 引入npm包。
```
npm install @arms/rum-browser --save
```
2. 初始化应用。
  说明
  请将以下代码中的pid和endpoint替换为当前应用对应的pid和endpoint地址。
```
import ArmsRum from '@arms/rum-browser';
ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint"
});
```
各安装方式说明如下：
- 异步加载：又称为非阻塞加载，表示浏览器在下载执行JS之后还会继续处理后续页面。若对页面性能的要求非常高，建议使用此方式。
  重要
  由于是异步加载，ARMS无法捕捉到监控SDK加载初始化完成之前的JS错误和资源加载错误。
- 同步加载：又称为阻塞加载，表示当前JS加载完毕后才会进行后续处理。如需捕捉从页面打开到关闭的整个过程中的JS错误和资源加载错误，建议使用此方式。
- npm包：使用npm包可以减少页面中Script的加载个数，可以自行控制页面Script的CDN业务方向，并可以将用户体验监控作为单独模块进行后续处理。
使用CDN加载情况下，访问 SDK 监控实例，请使用全局命名空间 RumSDK.default
```
const ArmsRum = window.RumSDK.default;
// 访问 RumSDK 需确保SDK已经完成加载
// 如果SDK加载前没有定义 __rum 配置，可在此初始化
ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
});
// 以下继续使用，NPM 和 CDN 一致
ArmsRum.setConfig('env', 'pre');
```

SDK 配置

参数	类型	描述	是否必填	默认值
pid	string	应用ID	是	-
endpoint	string	上报地址	是	-
env	-	应用环境： prod：线上环境 gray：灰度环境 pre：预发环境 daily：日常环境 local：本地环境	否	prod
version	string	应用版本	否	-
user	object	User配置	否	user.id由SDK默认生成
spaMode	string	SPA模式，监听页面事件并重新上报PV，适用于单页面应用场景。 hash history auto false	否	false
collectors	object	各Collector（采集器）配置	否	-
beforeReport	function	Repoter发送RUM事件之前	否	-
reportConfig	object	上报配置，详细说明请参见reportConfig 配置。	否	{ flushTime: 3000, maxEventCount: 20 }
parseViewName	function	解析视图名称（view.name），入参为当前页面的URL。	否	-
parseResourceName	function	解析资源名称（resource.name），入参为当前资源的URL。	否	-
evaluateApi	function	自定义解析API事件，详细说明请参见evaluateApi 配置。	否	-
filters	object	事件过滤配置，详情说明请参见filters 配置。	否	-
whiteScreen	object	白屏监控配置，详细说明请参见whiteScreen 配置。	否	-
properties	object	自定义属性，可对所有事件生效，详情说明请参见properties 配置。	否

user 配置

参数	类型	描述	是否必填	默认值
id	string	用户ID，不可修改。	否	由SDK默认生成
tags	string	标签	否	-
name	string	名称	否	-

示例

说明

如果需要关联业务自有账号体系，建议使用user.name或者user.tags ，而不是修改user.id。强制覆盖SDK生成的user.id ，会影响UV的计算。

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
  user: {
    name: 'your user.name',
    tags: 'your user.tags',
  },
});

reportConfig 配置

参数	类型	描述	是否必填	默认值
flushTime	number	上报时间间隔取值范围：[0, 10000]	否	3000
maxEventCount	number	一次上报最大数量取值范围：[1, 100]	否	20
storage	string	Session相关的数据存储位置 cookie localStorage	否	localStorage

Storage存储了user.id和session信息：

_arms_uid：唯一标识用户ID，对应user.id
_arms_session：具备语义化的session信息
- sessionId：session唯一标识
- sampled：是否命中采样
- startTime：session的开始时间戳
- lastTime：session最后一次活跃时间戳

`${sessionId}-${sampled}-${startTime}-${lastTime}`

示例

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpint",
  reportConfig: {
    storage: 'cookie', // 将 Session 标识存储改为 Cookie 方式存储
    flushTime: 0, // 立即上报
    maxEventCount: 50, // 一次最多上报数量
  },
});

collectors 配置

Collector是RUM SDK用于收集页面监控数据的最小单元。目前RUM SDK内置了api、static Resource等丰富的采集器。

参数	类型	描述	是否必填	默认值
perf	boolean \| object	监听页面的性能数据。	否	true
webvitals	boolean \| object	监听页面的WebVitals数据。	否	true
api	boolean \| object	监听API请求。	否	true
staticResource	boolean \| object	监听静态资源请求。	否	true
consoleError	boolean \| object	监听Console错误。	否	true
jsError	boolean \| object	监听JS错误。	否	true
action	boolean \| object	监听用户行为。	否	true

示例

关闭监听用户Click行为。

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
  collectors: {
    action: false,
  },
});

evaluateApi 配置

evaluateApi提供对API（XMLHttpRequest/fetch）事件的自定义解析。以下为SDK传入的三个参数：

参数	类型	描述
options	object	请求参数，包括url、headers、data等，根据具体请求方式有所差异。
response	object	请求响应体。
error	Error	可选参数，当请求失败才会传入。

该函数支持异步函数，返回Promise<IApiBaseAttr>，IApiBaseAttr的定义如下：

参数	类型	描述	是否必填
name	string	API名称，一般是对URL的收敛，最大1000字符。例如URL为`/list/123`，收敛name字段后显示为`/list/$id`。重要该字段的优先级高于parseResourceName返回的内容。	否
message	string	API信息，一个简短的描述API概况字符串，最大1000字符。	否
success	number	请求成功状态： 1：成功 0：失败 -1：未知	否
duration	number	API总耗时。	否
status_code	number \| string	API状态码。	否
snapshots	string	API快照。说明可用于存储reqHeaders、params、resHeaders等，具体字段组成方式可自行决定。该字段主要用于排查接口异常的原因，没有索引，不能根据该字段进行筛选或聚合，只接受字符串类型，最大5000字符。	否

示例

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpint",
  evaluateApi: async (options, response, error) => {
    let respText = '';
    // 当前为使用fetch请求的情况
    if (response && response.text) {
      respText = await response.text();
    }
    // 返回的字段会覆盖默认内容，不返回的字段会依然使用SDK自定生成内容
    return {
      name: 'my-custom-api',
      success: error ? 0 : 1,
      // 以下可选
      snapshots: JSON.stringify({
        params: 'page=1&size=10', // 请求入参
        response: respText.substring(0, 2000), // 返回值
        reqHeaders: '', // 请求头
        resHeaders: '', // 响应头
      }),
      properties: {
        prop_msg: 'custom msg',
        prop_num: 1,
      },
    };
  },
});

filters 配置

filters 用于对过滤无需上报的事件，目前支持 resource 和 exception 两种事件。

参数	类型	描述	是否必填
resource	MatchOption \| MatchOption[]	对采集到的资源事件进行过滤，包括静态资源和API（XMLHttpRequest/fetch）	否
exception	MatchOption \| MatchOption[]	对采集到的异常事件进行过滤。	否

MatchOption

type MatchOption = string | RegExp | ((value: string) => boolean);

string：匹配任何以该值开头的URL，如https://api.aliyun.com可以匹配https://api.aliyun.com/v1/resource。
RegExp：使用提供的RegExp和URL执行test。
function：以URL作为参数进行计算，返回true表示匹配。

当传入为 MatchOption[] 时，条件顺序执行，有一项满足就会被过滤。

示例

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
  filters: {
    // 过滤异常
    exception: [
      'Test error', // 以'Test error'开头的error.message
      /^Script error\.?$/, // 正则表达式匹配 error.message
      (msg) => {
        return msg.includes('example-error');
      },
    ],
    // 过滤资源或API
    resource: [
      'https://example.com/', // 以'https://example.com/'开头的resource
      /localhost/i,
      (url) => {
        return url.includes('example-resource');
      },
    ],
  },
});

whiteScreen 配置

白屏监控仅支持浏览器端（Chrome 40+，IE 9+）。

参数	类型	描述
detectionRules	`Array<DetectionRule>`	包含一个或多个白屏检测规则，按配置顺序和延时大小触发检测。

DetectionRule

参数	类型	是否必填	描述	默认值
target	`String`	是	指定白屏检测的目标元素的选择器。当检测触发时，系统将对匹配此选择器的元素区域进行白屏检测。	无
test_when	`Array`	是	列出触发白屏检测的事件，检测将在这些事件发生后启动，可选值： `LOAD`：页面加载完成。 `ERROR`：发生全局JavaScript错误。 `ROUTE_CHANGE`：路由变化（包括hash和history）。 `LEAVE`：关闭页面前。	无
delay	`Number`	否	配合`test_when`使用。在指定事件（不包括`ERROR`和`LEAVE`）发生后，等待指定时间后开始白屏检测。（单位：毫秒）。	`0`
tester	`String \| Function`	是	定义使用的白屏检测方法。 `HAS_CONTENT`：内置检测方法，判断目标节点内是否含有 textContent。 `SAMPLE`：内置检测方法，通过设置采样点，判断采样点位置最顶层的DOM元素是否包含在给定的元素集合中，以计算白屏率。 `SCREENSHOT`：内置检测方法，通过canvas截图，基于像素比对计算白屏率。自定义检测函数：入参为目标元素，返回值类型为`CustomTesterResult`或`Promise<CustomTesterResult>`，类型声明见表格下方。	无
ignoreUrlList	`Array<String>`	否	需要忽略检测的URL列表，当页面URL与列表中的任何一个匹配时，不进行白屏检测。	`[]`
configOptions	`ConfigOptions`	否	和`tester`搭配使用，为所选`tester`提供具体的配置参数。	详见`ConfigOptions`的配置项说明

CustomTestResult的类型声明：

type CustomTesterResult = {
  /**
   * 是否存在内容，如果为`true`则表示有内容，`false`表示发生白屏。
   */
  hasContent: boolean;

  /**
   * 错误信息
   */
  message?: string;

  /**
   * 异常的快照数据
   */
  snapshot?: Record<string, any>;
}

ConfigOptions

参数仅在关联方法中生效。

参数	类型	关联方法	描述	默认值
colorRange	`Array<Srting>`	`SCREENSHOT`	视为白屏的颜色集合，用于像素比对时判断当前像素区块是否为“全白”，格式为`rgb(r, g, b)`。	`['rgb(255, 255, 255)']`
fillColor	`String`	`SCREENSHOT`	填充颜色。在截图时会对图片、视频、canvas、svg、iframe 等元素进行色块填充，填充色不能是`colorRange`里配置的任何一种颜色。	`'rgba(0, 100, 200, 255)'`
horizontalOffset	`Number`	`SCREENSHOT`	白屏检测区域左侧边缘相对于目标元素左侧边缘的水平偏移量，用于过滤目标元素的左侧菜单。	`0`
verticalOffset	`Number`	`SCREENSHOT`	白屏检测区域上边缘相对于目标元素上边缘的垂直偏移量，用于过滤目标元素的 topBar。	`0`
pixels	`Number`	`SCREENSHOT`	指定白屏检测时，采样像素区块的大小，区块的大小为`pixels * pixels`。	`10`
threshold	`Number`	`SCREENSHOT` `SAMPLE`	白屏率阈值，当白屏率大于该值时，认为发生白屏。	`0.8`
dpr	`Number`	`SCREENSHOT`	设置快照图片的缩放比例。	`0.3`
ignoreElements	`Array<Srting>`	`SCREENSHOT`	需要忽略检测的元素的 CSS 选择器，这些元素在截图时将被忽略。	`[]`
sampleMethod	`1 \| 2 \| 3`	`SAMPLE`	采样方法： `1`：十字采样 `2`：交叉十字采样 `3`：米字采样	`2`
checkPoints	`Number`	`SAMPLE`	设置径向的采样点数量。对于十字采样或交叉十字采样，总采样点数量为 `4 * checkPoints + 1`。对于米字采样，总采样点数量为 `8 * checkPoints + 1`。	`10`
whiteBoxElements	`Array<Srting>`	`SAMPLE`	白屏元素的 CSS 选择器列表，当采样点的顶层 DOM 元素匹配此列表中的选择器时，增加白屏计数。	`[]`
debug	`Boolean`	`SCREENSHOT` `SAMPLE`	是否开启调试模式，在调试模式下可以在开发者工具里看到打印的检测信息。	`false`

示例

SCREENSHOT 截图检测法

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpint",
  whiteScreen: {
    detectionRules: [{
      target: '#root',
      test_when: ['LOAD', 'ERROR', 'ROUTE_CHANGE', 'LEAVE'],
      delay: 5000,
      tester: 'SCREENSHOT',
      configOptions: {
        colorRange: ['rgb(255, 255, 255)', 'rgb(0, 0, 0)'],
        threshold: 0.9,
        pixels: 10,
        horizontalOffset: 210,
        verticalOffset: 50,
      },
    }],
  },
});

SAMPLE 采样法

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpint",
  whiteScreen: {
    detectionRules: [{
      target: '#root',
      test_when: ['LOAD', 'ERROR', 'ROUTE_CHANGE', 'LEAVE'],
      delay: 5000,
      tester: 'SAMPLE',
      configOptions: {
        sampleMethod: 2,
        checkPoints: 10,
        threshold: 0.9,
        whiteBoxElements: ['.el-skeleton'],
      },
    }],
  },
});

CUSTOM 自定义检测函数

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpint",
  whiteScreen: {
    detectionRules: [{
      target: '#root',
      test_when: ['LOAD', 'ERROR', 'ROUTE_CHANGE', 'LEAVE'],
      delay: 5000,
      tester: async (element) => {
        // 自定义检测函数主题
        return {
          hasContent: false,
          message: '自定义的错误信息',
          snapshot: {
            // 键值对可自定义
            checkPoints: 100,
            rate: 0.99,
            checkdata: '......',
          },
        };
      },
    }],
  },
});

properties 配置

Properties是RUM提供的自定义属性，可为任何上报的事件

参数	类型	描述	是否必填
[key: string]	string \| number	key必须是符合JSON规范的字符串，key的最大长度为50字符，key超出部分会被截断。 value为string时，最大长度为2000字符。value为非 string \| number时，该键值对会被移除。	否

使用evaluateApi、sendCustom、sendException、sendResource等可以单独为某个事件增加properties，仅对单个事件生效。

全局properties和事件properties在存储时会进行合并。事件properties优先级高于全局properties，合并时相同的key，事件properties会覆盖全局properties。合并后properties键值对数量不可超过20对，超出会基于key进行排序后移除。

示例

全局配置properties时，所有上报的事件都会拥有。

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
  properties: {
    prop_string: 'xx',
    prop_number: 2,
    // key 和 value 超出范围会被截断
    more_than_50_key_limit_012345678901234567890123456789: 'yy',
    more_than_2000_value_limit: new Array(2003).join('1'),
    // 以下不符合要求的键值对会被移除
    prop_null: null,
    prop_undefined: undefined,
    prop_bool: true,
  },
});

其他配置

RUM SDK支持配置基于IP和UserAgent等解析所得到的公共属性，主动配置字段优先级高于自动解析。

参数	类型	描述	是否必填
device	object	设备信息	否
os	object	系统、容器信息	否
geo	object	行政地理信息	否
isp	object	运营商信息	否
net	object	网络信息	否

以上字段具体可配置项请参考日志数据说明中公共属性部分。

示例

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
  geo: {
    country: 'your custom cuntry info',
    city: 'your custom city info',
  },
});

SDK API

RUM SDK开放API，用于修改上报自定义数据，动态修改SDK配置等。

getConfig

获取SDK配置。

setConfig

修改SDK配置。

// 指定 key 设置
ArmsRum.setConfig('env', 'pre');

// 覆盖设置
const config = ArmsRum.getConfig();
ArmsRum.setConfig({
  ...config,
  version: '1.0.0',
  env: 'pre',
});

sendCustom

上报自定义数据，必须包含type和name两个属性，否则无法上报。属性的具体业务意义可参考下表，实际使用需要自行定义业务语义。

参数	类型	描述	是否必填
type	string	类型	是
name	string	名称	是
group	string	分组	否
value	number	值	否
properties	object	自定义属性	否

ArmsRum.sendCustom({
  // 必选
  type: 'CustomEvnetType1',
  name: 'customEventName2',
  // 可选
  group: 'customEventGroup3',
  value: 111.11,
  properties: {
    prop_msg: 'custom msg',
    prop_num: 1,
  },
});

sendException

上报自定义异常数据，必须包含name和message两个属性，否则无法上报。

参数	类型	描述	是否必填
name	string	异常名称	是
message	string	异常信息	是
file	string	异常发生文件	否
stack	string	异常堆栈信息	否
line	number	异常发生的行数	否
column	number	异常发生的列数	否
properties	object	自定义属性	否

ArmsRUM.sendException({
  // 必选
  name: 'customErrorName',
  message: 'custom error message',
  // 可选
  file: 'custom exception filename',
  stack: 'custom exception error.stack',
  line: 1,
  column: 2,
  properties: {
    prop_msg: 'custom msg',
    prop_num: 1,
  },
});

sendResource

上报自定义资源，必须包含name、type和duration三个属性，否则无法上报。

参数	类型	描述	是否必填
name	string	资源名。	是
type	string	资源类型，例如：css、javascript、xmlhttprequest、fetch、api、image、font、other。	是
duration	string	请求耗时。	是
success	number	请求成功状态： 1：成功 0：失败 -1：未知	否
method	string	请求方法。	否
status_code	number \| string	请求状态码。	否
message	string	请求消息。	否
url	string	请求地址。	否
trace_id	string	链路追踪ID。	否
properties	object	自定义属性	否

ArmsRum.sendResource({
  // 以下必选
  name: 'getListByPage',
  message: 'success',
  duration: 800,
  // 以下可选
  url: 'https://www.aliyun.com/data/getListByPage',
  properties: {
    prop_msg: 'custom msg',
    prop_num: 1,
  },
});