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

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

重要

阿里云用户体验监控于2023年12月08日开启公测，公测期间您可以免费试用阿里云用户体验监控，如果您在使用中有任何问题，请联系用户体验监控答疑钉钉群（群号：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业务方向，并可以将用户体验监控作为单独模块进行后续处理。

SDK配置

参数	类型	描述	是否必填	默认值
pid	string	应用ID	是	-
endpoint	string	上报地址	是	-
env	-	应用环境： prod：线上环境 gray：灰度环境 pre：预发环境 daily：日常环境 local：本地环境	否	prod
version	string	应用版本	否	-
user	object	User配置	否	user.id由SDK默认生成
collectors	object	各Collector（采集器）配置	否	-
beforeReport	function	Repoter发送RUM事件之前	否	noop
reportConfig	object	上报配置	否	{ flushTime: 3000, maxEventCount: 50 }
parseViewName	function	解析视图名称（view.name），入参为当前页面的URL。	否	-
parseResourceName	function	解析资源名称（resource.name），入参为当前资源的URL。	否	-
evaluateApi	function	自定义解析API事件，详细说明请参见evaluateApi配置。	否	-
whiteScreen	object	白屏监控配置，详细说明请参见whiteScreen配置。	否	-

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: getYourUserName(),
    tags: getYourTags(),
  }
});

reportConfig配置

参数

类型

描述

是否必填

默认值

flushTime

number

上报时间间隔

取值范围：[0, 10000]

否

3000

maxEventCount

number

一次上报最大数量

取值范围：[1, 100]

否

示例

说明

使用业务自有账号体系强制覆盖SDK生成的user.id，会对影响UV的计算。

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpint",
  reportConfig: {
    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: '' // 响应头
      })
    }
  }
});

whiteScreen配置

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

参数	类型	描述	默认值
detectionRules	Array	包含一个或多个白屏检测规则，按配置顺序和延时大小触发检测。	无
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。 `SCREENSHOT`：内置检测方法，通过canvas截图获取白屏率。自定义检测函数：入参为目标元素，返回值类型为boolean，返回值为false表示检测到白屏，为true表示未检测白屏。	无
configOptions	Object	和tester搭配使用，为所选tester提供具体的配置参数。 `colorRange`：指定要检测的颜色范围，默认为白色（255，255，255）。 `fillColor`：填充颜色。在截图时会默认对图片、视频、Canvas、Svg、iframe等元素进行色块填充，填充色不能是colorRange里配置的任何一种颜色。 `horizontalOffset`：在截取屏幕快照时，相对于目标区域的水平偏移量。 `verticalOffset`：在截取屏幕快照时，相对于目标区域的垂直偏移量。 `pixels`：指定在截图中随机采样的像素数量，默认为10x10。 `threshold`：设定白屏阈值，若命中白屏的像素点个数大于这个阈值，则认为白屏。 `dpr`：设定屏幕快照缩放比例。 `debug`：控制是否开启调试模式。在调试模式下可以在开发者工具里看到打印的检测信息。 `ignoreUrlList`：列出需要忽略检测的URL列表。当页面URL与列表中的任何一个匹配时，不进行截图检测。 `ignoreElements`：列出需要忽略检测的元素选择器，当截图中包含任一匹配的元素时，不进行检测。	目前仅在SCREENSHOT方法下生效，默认值为： colorRange: ['rgb(255, 255, 255)'] fillColor: 'rgba(0, 100, 200, 255)' horizontalOffset: 0 verticalOffset: 0 pixels: 10 threshold: 0.8 dpr: 0.3 debug: false ignoreUrlList: [] ignoreElements: []

示例

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,
      }
    }],
  }
});

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	值	否	-

ArmsRum.sendCustom({
  type: 'CustomEvnetType1',
  name: 'customEventName2',
  group: 'customEventGroup3',
  value: 111.11
});

sendException

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

参数	类型	描述	是否必填	默认值
name	string	异常名称	是	-
message	string	异常信息	是	-
file	string	异常发生文件	否	-
stack	string	异常堆栈信息	否	-
line	number	异常发生的行数	否	-
column	number	异常发生的列数	否	-

ArmsRum.sendCustom({
  // 必选
  name: 'customErrorName',
  message: 'custom error message',
  // 可选
  file: 'custom exception filename',
  stack: 'custom exception error.stack',
  line: 1,
  column: 2
});

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。	否	-

ArmsRum.sendResource({
  // 必选
  name: 'getListByPage',
  message: 'success',
  duration: 800,
  // 可选
  url: 'https://www.aliyun.com/data/getListByPage',
});