@arms/rum-reactnative

阿里云ARMS用户体验监控React Native SDK，用于在React Native应用中采集前端性能、异常及用户行为数据，并上报至ARMS控制台。

功能特性

• API性能监控 — 自动拦截 XMLHttpRequest / fetch 请求，采集耗时、状态码等指标
• JS错误捕获 — 自动捕获 JavaScript 运行时异常
• 控制台错误监听 — 监听 console.error 输出
• 链路追踪 — 支持多种传播协议的分布式链路追踪
• 页面导航追踪 — 集成 React Navigation，自动追踪页面切换
• 自定义事件上报 — 支持自定义业务数据、异常、资源、视图等事件上报
• Session管理 — 自动管理用户会话，支持采样率和超时配置

安装

npm install @arms/rum-reactnative @react-native-async-storage/async-storage

快速开始

在应用入口处初始化SDK：

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

armsRum.init({
  endpoint: '<your-endpoint>'
});

说明：endpoint 可在ARMS控制台创建应用后获取；

配置项

基础配置

| 配置项 | 类型 | 必填 | 默认值 | 说明 | |-------|------|------|-------|------| | endpoint | string | 是 | - | 数据上报地址 | | env | string | 否 | 'prod' | 环境：'prod' | 'gray' | 'pre' | 'daily' | 'local' | | version | string | 否 | - | 应用版本号 | | user | object | 否 | - | 用户信息配置 | | collectors | object | 否 | - | 采集器配置 | | tracing | boolean | object | 否 | false | 链路追踪配置 | | filters | object | 否 | - | 事件过滤配置 | | properties | object | 否 | - | 全局自定义属性 | | reportConfig | object | 否 | - | 上报配置 | | sessionConfig | object | 否 | - | Session配置 | | beforeReport | function | 否 | - | 上报前钩子函数 | | parseViewName | function | 否 | - | 自定义解析页面名称 | | parseResourceName | function | 否 | - | 自定义解析资源名称 | | evaluateApi | function | 否 | - | 自定义API事件解析 |

user 用户配置

| 字段 | 类型 | 说明 | |------|------|------| | name | string | 用户名称（建议关联业务账号） | | tags | string | 用户标签 |

注意：user.id 由SDK自动生成并维护，不可自行设置。

collectors 采集器配置

| 采集器 | 类型 | 默认值 | 说明 | |--------|------|-------|------| | api | boolean | object | true | API请求监控（XMLHttpRequest / fetch） | | jsError | boolean | object | true | JavaScript运行时错误捕获 | | consoleError | boolean | object | true | console.error监听 |

sessionConfig Session配置

| 字段 | 类型 | 默认值 | 说明 | |------|------|-------|------| | sampleRate | number | 1 | 采样率，范围 [0, 1]，0.5 表示 50% 采样 | | maxDuration | number | 86400000 | Session最大持续时间（毫秒），默认24小时 | | overtime | number | 3600000 | Session超时时间（毫秒），默认1小时无活动则过期 |

reportConfig 上报配置

| 字段 | 类型 | 默认值 | 说明 | |------|------|-------|------| | flushTime | number | 3000 | 上报时间间隔（ms），范围 [0, 10000]，0 表示立即上报 | | maxEventCount | number | 20 | 单次上报最大事件数，范围 [1, 100] |

tracing 链路追踪

支持布尔值开关或详细配置对象：

tracing: {
  enable: true,
  sample: 0.1, // 10% 采样
  propagatorTypes: ['tracecontext', 'b3'],
  allowedUrls: [
    { match: 'https://api.example.com/', propagatorTypes: ['tracecontext'] }
  ]
}

支持的传播协议：

| 协议 | 说明 | |------|------| | tracecontext | W3C Trace Context | | b3 | Zipkin B3 单头传播 | | b3multi | Zipkin B3 多头传播 | | jaeger | Jaeger | | sw8 | SkyWalking |

filters 事件过滤

filters: {
  resource: ['https://cdn.example.com/', /localhost/i],
  exception: [/^Script error/, (msg) => msg.includes('ignore')],
  view: ['/internal/']
}

过滤规则支持以下类型：

| 类型 | 说明 | |------|------| | 字符串 | 前缀匹配，匹配到则过滤 | | 正则表达式 | 正则匹配，匹配到则过滤 | | 函数 | 返回 true 表示过滤该事件 |

API方法

armsRum.init(config)

初始化SDK，应在应用启动时调用。调用后SDK将根据配置自动开始数据采集和上报。

armsRum.setConfig(key, value) / armsRum.setConfig(config)

动态更新SDK配置。

// 单个配置更新
armsRum.setConfig('version', '1.2.0');

// 批量配置更新
armsRum.setConfig({
  version: '1.2.0',
  env: 'pre',
});

armsRum.getConfig()

获取当前SDK配置对象。

事件上报

| 方法 | 说明 | |------|------| | armsRum.sendCustom(payload) | 上报自定义业务数据 | | armsRum.sendException(payload \| Error) | 上报自定义异常 | | armsRum.sendResource(payload) | 上报自定义资源事件 | | armsRum.sendView(payload) | 上报自定义视图事件 | | armsRum.sendEvent(payload) | 上报自定义事件 |

页面导航追踪

| 方法 | 说明 | |------|------| | armsRum.startTrackingViews(navigationRef) | 启动页面追踪 | | armsRum.stopTrackingViews() | 停止页面追踪 |

高级用法

React Navigation 集成

方式一：onReady 回调模式

import React, { useRef } from 'react';
import { NavigationContainer } from '@react-navigation/native';
import armsRum from '@arms/rum-reactnative';

export default function App() {
  const navigationRef = useRef(null);

  return (
    <NavigationContainer
      ref={navigationRef}
      onReady={() => {
        armsRum.startTrackingViews(navigationRef.current);
      }}
    >
      {/* 路由配置 */}
    </NavigationContainer>
  );
}

方式二：Hook 模式（推荐）

import React, { useEffect } from 'react';
import { useNavigationContainerRef } from '@react-navigation/native';
import armsRum from '@arms/rum-reactnative';

export default function App() {
  const navigationContainerRef = useNavigationContainerRef();

  useEffect(() => {
    armsRum.startTrackingViews(navigationContainerRef.current);
  }, []);

  return (
    <NavigationContainer ref={navigationContainerRef}>
      {/* 路由配置 */}
    </NavigationContainer>
  );
}

自定义API解析（evaluateApi）

当默认的API事件解析逻辑不满足需求时，可通过 evaluateApi 自定义解析。函数接收以下参数：

• request — 请求信息
• response — 响应信息
• error — 错误信息
• xhr — 原始XHR对象

返回值为 IApiBaseAttr 对象：

armsRum.init({
  endpoint: '<your-endpoint>',
  evaluateApi: async (request, response, error) => {
    return {
      name: '/api/list',
      success: error ? 0 : 1,
      duration: 100,
      snapshots: JSON.stringify({ params: 'page=1' }),
    };
  }
});

自定义事件上报示例

// 自定义业务事件
armsRum.sendCustom({
  name: 'order_placed',
  properties: { order_id: 'ORD-12345', amount: 99.99 }
});

// 手动上报异常
try {
  // 业务逻辑
} catch (error) {
  armsRum.sendException(error);
}

beforeReport 钩子

在事件上报前进行修改或过滤：

armsRum.init({
  beforeReport(event) {
    // 返回修改后的event，返回 false 则丢弃该事件
    return event;
  }
});

完整配置示例

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

armsRum.init({
  // 基础配置
  endpoint: '<your-endpoint>',
  env: 'prod',
  version: '1.0.0',

  // 用户配置
  user: {
    name: 'zhangsan',
    tags: 'vip',
  },

  // 采集器配置
  collectors: {
    api: true,
    jsError: true,
    consoleError: true,
  },

  // 链路追踪
  tracing: {
    enable: true,
    sample: 0.1,
    propagatorTypes: ['tracecontext'],
    allowedUrls: [
      { match: 'https://api.example.com/', propagatorTypes: ['tracecontext'] }
    ],
  },

  // 事件过滤
  filters: {
    resource: ['https://cdn.example.com/'],
    exception: [/^Script error/],
  },

  // 全局自定义属性
  properties: {
    channel: 'appstore',
  },

  // 上报配置
  reportConfig: {
    flushTime: 5000,
    maxEventCount: 30,
  },

  // Session配置
  sessionConfig: {
    sampleRate: 1,
    maxDuration: 86400000,
    overtime: 3600000,
  },

  // 上报前钩子
  beforeReport(event) {
    return event;
  },
});

相关文档

• ARMS用户体验监控文档