SDK配置参考

更新时间:2025-03-04 10:04:17

ARMS 用户体验监控提供一系列SDK配置项,让您能够通过设置参数来满足额外需求。本文介绍小程序应用常用的 SDK 配置。

SDK 配置

参数

类型

描述

是否必填

默认值

参数

类型

描述

是否必填

默认值

pid

String

应用ID

-

endpoint

String

上报地址

-

env

-

应用环境:

  • prod:线上环境

  • gray:灰度环境

  • pre:预发环境

  • daily:日常环境

  • local:本地环境

prod

version

String

应用版本

-

user

Object

User配置

user.idSDK默认生成

collectors

Object

Collector(采集器)配置

-

beforeReport

Function

上报数据之前执行beforeReport,可以修改或阻止数据上报。

noop

reportConfig

Object

上报配置

{

flushTime: 3000,

maxEventCount: 20

}

sessionConfig

Object

Session的采样、超时时间等配置,详细说明请参见sessionConfig 配置

-

parseViewName

Function

解析视图名称(view.name),入参为当前页面的URL。

-

parseResourceName

Function

解析资源名称(resource.name),入参为当前资源的URL。

-

evaluateApi

Function

自定义解析API事件,详细说明请参见evaluateApi配置

-

filters

Object

事件过滤配置,详情说明请参见filters 配置

-

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

reportConfig 配置

参数

类型

描述

是否必填

默认值

参数

类型

描述

是否必填

默认值

flushTime

Number

上报时间间隔

取值范围:[0, 10000]

3000

maxEventCount

Number

一次上报最大数量

取值范围:[1, 100]

20

示例

说明

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

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpint",
  reportConfig: {
    flushTime: 0, // 立即上报
    maxEventCount: 50 // 一次最多上报数量
  }
});

sessionConfig 配置

参数

类型

描述

是否必填

默认值

参数

类型

描述

是否必填

默认值

sampleRate

Number

Session采样率:[0, 1]

0.550%采样率。

1

maxDuration

Number

Session最大持续时间,默认24小时。单位:毫秒。

86400000

overtime

Number

Session超时时间,默认半小时。单位:毫秒。

1800000

小程序本地缓存中存储了user.idsession信息 :

  • _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",
  sessionConfig: {
    sampleRate: 0.5, // 采样率50%
    maxDuration: 86400000,
    overtime: 3600000,
  },
});

Collectors配置

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

参数

类型

描述

是否必填

默认值

参数

类型

描述

是否必填

默认值

api

Boolean | Object

监听API请求。

true

jsError

Boolean | Object

监听JS错误。

true

consoleError

Boolean | Object

监听console.error抛出的错误。

true

action

Boolean | Object

监听用户行为。

true

示例

关闭监听用户Click行为。

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

evaluateApi配置

evaluateApi提供对API(requesthttpRequest)事件的自定义解析。以下为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) => {
    const respText = JSON.stringify(response);

    // 返回的字段会覆盖默认内容,不返回的字段会依然使用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: '' // 响应头
      })
    }
  }
});

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:使用提供的RegExpURL执行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');
      },
    ],
  },
});

properties 配置

PropertiesRUM提供的自定义属性,可为任何上报事件配置该属性。

参数

类型

描述

是否必填

参数

类型

描述

是否必填

[key: string]

String | Number

  • key必须是符合JSON规范的字符串,key的最大长度为50字符,超出部分会被截断。

  • valueString时,最大长度为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支持配置基于IPUserAgent等解析所得到的公共属性,主动配置字段优先级高于自动解析。

参数

类型

描述

是否必填

参数

类型

描述

是否必填

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

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

参数

类型

描述

是否必填

默认值

参数

类型

描述

是否必填

默认值

type

String

类型

-

name

String

名称

-

group

String

分组

-

value

Number

-

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

sendException

上报自定义异常数据,必须包含namemessage两个属性,否则无法上报。

参数

类型

描述

是否必填

默认值

参数

类型

描述

是否必填

默认值

name

String

异常名称

-

message

String

异常信息

-

file

String

异常发生文件

-

stack

String

异常堆栈信息

-

line

Number

异常发生的行数

-

column

Number

异常发生的列数

-

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

sendResource

上报自定义资源,必须包含name、typeduration三个属性,否则无法上报。

参数

类型

描述

是否必填

默认值

参数

类型

描述

是否必填

默认值

name

String

资源名。

-

type

String

资源类型,例如:script、api、image、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',
});
  • 本页导读 (1)
  • SDK 配置
  • user 配置
  • 示例
  • reportConfig 配置
  • 示例
  • sessionConfig 配置
  • 示例
  • Collectors配置
  • 示例
  • evaluateApi配置
  • 示例
  • filters 配置
  • MatchOption
  • 示例
  • properties 配置
  • 示例
  • 其他配置
  • 示例
  • SDK API
  • getConfig
  • setConfig
  • sendCustom
  • sendException
  • sendResource