@arms/rum-reactnative 0.1.1 → 0.1.3-beta.0

package/docs/ReactNative SDK/351/205/215/347/275/256/345/217/202/350/200/203.md"

@@ -0,0 +1,671 @@
+# React Native SDK配置参考
+
+ARMS用户体验监控React Native SDK提供一系列配置项，让您能够通过设置参数来满足额外需求。本文介绍React Native应用常用的SDK配置。
+
+## SDK配置
+
+| 参数 | 类型 | 描述 | 是否必填 | 默认值 |
+|------|------|------|----------|--------|
+| endpoint | string | 上报地址 | 是 | - |
+| env | string | 应用环境：<br/>• `prod`：线上环境<br/>• `gray`：灰度环境<br/>• `pre`：预发环境<br/>• `daily`：日常环境<br/>• `local`：本地环境 | 否 | `'prod'` |
+| version | string | 应用版本号 | 否 | - |
+| user | object | 用户信息配置，详细说明请参见[user配置](#user-配置) | 否 | - |
+| beforeReport | function | 上报前钩子函数，在发送RUM事件之前调用 | 否 | - |
+| reportConfig | object | 上报配置，详细说明请参见[reportConfig配置](#reportconfig-配置) | 否 | - |
+| sessionConfig | object | Session的采样、存储等配置，详细说明请参见[sessionConfig配置](#sessionconfig-配置) | 否 | - |
+| collectors | object | 采集器配置，详细说明请参见[collectors配置](#collectors-配置) | 否 | - |
+| tracing | boolean \| object | 链路追踪配置 | 否 | `false` |
+| parseResourceName | function | 解析资源名称（resource.name），入参为当前资源的URL | 否 | - |
+| parseViewName | function | 自定义解析页面名称 | 否 | - |
+| evaluateApi | function | 自定义解析API事件，详细说明请参见[evaluateApi配置](#evaluateapi-配置) | 否 | - |
+| filters | object | 事件过滤配置，详细说明请参见[filters配置](#filters-配置) | 否 | - |
+| properties | object | 自定义属性，可对所有事件生效，详细说明请参见[properties配置](#properties-配置) | 否 | - |
+
+## user 配置
+
+| 参数 | 类型 | 描述 | 是否必填 | 默认值 |
+|------|------|------|----------|--------|
+| name | string | 用户名称，作为业务用户标识 | 否 | - |
+| tags | string | 用户标签 | 否 | - |
+
+> **说明**：如果需要关联业务自有账号体系，建议使用`user.name`或者`user.tags`，而不是修改`user.id`。强制覆盖SDK生成的`user.id`，会影响UV的计算。`user.id`由SDK自动生成并维护，不可自行设置。
+
+### 示例
+
+```typescript
+armsRum.init({
+  endpoint: '<your-endpoint>',
+  user: {
+    name: 'zhangsan',
+    tags: 'vip',
+  },
+});
+```
+
+## reportConfig 配置
+
+| 参数 | 类型 | 描述 | 是否必填 | 默认值 |
+|------|------|------|----------|--------|
+| flushTime | number | 上报时间间隔（ms）<br/>取值范围：[0, 10000] | 否 | 3000 |
+| maxEventCount | number | 一次上报最大数量<br/>取值范围：[1, 100] | 否 | 20 |
+
+### 示例
+
+```typescript
+armsRum.init({
+  endpoint: '<your-endpoint>',
+  reportConfig: {
+    flushTime: 0,      // 立即上报
+    maxEventCount: 50, // 一次最多上报50个事件
+  },
+});
+```
+
+> **注意**：`flushTime`设置为0时会立即上报每个事件，生产环境建议保持默认值或适当增大以减少网络请求频率。
+
+## sessionConfig 配置
+
+| 参数 | 类型 | 描述 | 是否必填 | 默认值 |
+|------|------|------|----------|--------|
+| sampleRate | number | Session采样率：[0, 1]<br/>例如：0.5表示50%采样率 | 否 | 1 |
+| maxDuration | number | Session最大持续时间，单位为毫秒(ms)<br/>默认24小时 | 否 | 86400000 |
+| overtime | number | Session超时时间，单位为毫秒(ms)<br/>默认1小时无活动则过期 | 否 | 3600000 |
+
+### Session存储说明
+
+SDK在本地存储了以下信息：
+
+- `_arms_uid`：唯一标识用户ID，对应`user.id`
+- `_arms_session`：具备语义化的Session信息，格式为：`${sessionId}-${sampled}-${startTime}-${lastTime}`
+  - `sessionId`：Session唯一标识
+  - `sampled`：是否命中采样
+  - `startTime`：Session的开始时间戳
+  - `lastTime`：Session最后一次活跃时间戳
+
+### 示例
+
+```typescript
+armsRum.init({
+  endpoint: '<your-endpoint>',
+  sessionConfig: {
+    sampleRate: 0.5,      // 采样率50%
+    maxDuration: 86400000, // Session最大持续24小时
+    overtime: 3600000,     // 1小时无活动则Session过期
+  },
+});
+```
+
+## collectors 配置
+
+Collector是RUM SDK用于收集React Native应用监控数据的最小单元。目前RUM SDK内置了API、异常等丰富的采集器。
+
+| 参数 | 类型 | 描述 | 是否必填 | 默认值 |
+|------|------|------|----------|--------|
+| api | boolean \| object | 监听API请求（XMLHttpRequest / fetch） | 否 | true |
+| jsError | boolean \| object | 监听JS错误 | 否 | true |
+| consoleError | boolean \| object | 监听Console错误 | 否 | true |
+
+### 示例
+
+关闭API请求监控：
+
+```typescript
+armsRum.init({
+  endpoint: '<your-endpoint>',
+  collectors: {
+    api: false,
+  },
+});
+```
+
+关闭所有采集器：
+
+```typescript
+armsRum.init({
+  endpoint: '<your-endpoint>',
+  collectors: {
+    api: false,
+    jsError: false,
+    consoleError: false,
+  },
+});
+```
+
+## tracing 链路追踪配置
+
+支持布尔值开关或详细配置对象：
+
+```typescript
+tracing: {
+  enable: true,           // 是否启用链路追踪
+  sample: 0.1,            // 采样率（0-1之间）
+  propagatorTypes: ['tracecontext', 'b3'],  // 传播协议类型
+  allowedUrls: [          // 允许注入追踪头的URL规则
+    {
+      match: 'https://api.example.com/',
+      propagatorTypes: ['tracecontext']
+    }
+  ]
+}
+```
+
+支持的传播协议：
+
+| 协议 | 说明 |
+|------|------|
+| `tracecontext` | W3C Trace Context |
+| `b3` | Zipkin B3 单头传播 |
+| `b3multi` | Zipkin B3 多头传播 |
+| `jaeger` | Jaeger |
+| `sw8` | SkyWalking |
+
+### 示例
+
+```typescript
+armsRum.init({
+  endpoint: '<your-endpoint>',
+  tracing: {
+    enable: true,
+    sample: 0.1,  // 10%采样
+    propagatorTypes: ['tracecontext'],
+    allowedUrls: [
+      {
+        match: 'https://api.example.com/',
+        propagatorTypes: ['tracecontext']
+      },
+      {
+        match: 'https://backend.example.com/',
+        propagatorTypes: ['b3', 'tracecontext']
+      }
+    ],
+  },
+});
+```
+
+## evaluateApi 配置
+
+`evaluateApi`提供对API（request）事件的自定义解析。SDK会传入以下三个参数：
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| request | object | 请求信息，包括url、headers、method等 |
+| response | object | 响应信息，包括status、headers、body等 |
+| error | Error | 可选参数，当请求失败时传入 |
+
+该函数支持异步函数，返回Promise<IApiBaseAttr>。IApiBaseAttr的定义如下：
+
+| 参数 | 类型 | 描述 | 是否必填 |
+|------|------|------|----------|
+| name | string | API名称，一般是对URL的收敛，最大1000字符。<br/>例如URL为`/list/123`，收敛name字段后显示为`/list/$id`。<br/>**重要**：该字段的优先级高于`parseResourceName`返回的内容 | 否 |
+| message | string | API信息，一个简短的用于描述API概况字符串，最大1000字符 | 否 |
+| success | number | 请求成功状态：<br/>• 1：成功<br/>• 0：失败<br/>• -1：未知 | 否 |
+| duration | number | API总耗时（毫秒） | 否 |
+| status_code | number \| string | API状态码 | 否 |
+| snapshots | string | API快照，可用于存储reqHeaders、params、resHeaders等。<br/>**说明**：该字段主要用于排查接口异常的原因，没有索引，不能根据该字段进行筛选或聚合，只接受字符串类型，最大5000字符 | 否 |
+
+### 示例
+
+```typescript
+armsRum.init({
+  endpoint: '<your-endpoint>',
+  evaluateApi: async (request, response, error) => {
+    // 返回的字段会覆盖默认内容，不返回的字段会依然使用SDK自动生成内容
+    return {
+      name: '/api/user/profile',
+      success: error ? 0 : 1,
+      duration: response?.duration || 0,
+      status_code: response?.status || 0,
+      snapshots: JSON.stringify({
+        params: request?.body || '',
+        reqHeaders: request?.headers || {},
+        resHeaders: response?.headers || {},
+      }),
+      properties: {
+        prop_msg: 'custom msg',
+        prop_num: 1,
+      },
+    };
+  },
+});
+```
+
+## filters 配置
+
+`filters`用于过滤无需上报的事件，目前支持`resource`和`exception`两种事件。
+
+| 参数 | 类型 | 描述 | 是否必填 |
+|------|------|------|----------|
+| resource | MatchOption \| MatchOption[] | 对采集到的资源事件进行过滤，包括静态资源和API（XMLHttpRequest/fetch） | 否 |
+| exception | MatchOption \| MatchOption[] | 对采集到的异常事件进行过滤 | 否 |
+| view | MatchOption \| MatchOption[] | 对采集到的视图事件进行过滤 | 否 |
+
+### MatchOption类型
+
+```typescript
+type MatchOption = string | RegExp | ((value: string, error?: Error) => boolean);
+```
+
+- **string**：匹配任何以该值开头的URL，如`https://api.aliyun.com`可以匹配`https://api.aliyun.com/v1/resource`
+- **RegExp**：使用提供的RegExp和URL执行test
+- **function**：以URL作为参数进行计算，返回true表示匹配。当过滤异常的时候会传入第二个参数为Error对象
+
+当传入为`MatchOption[]`时，条件顺序执行，有一项满足就会被过滤。
+
+### 示例
+
+```typescript
+armsRum.init({
+  endpoint: '<your-endpoint>',
+  filters: {
+    // 过滤异常
+    exception: [
+      'Test error',              // 以'Test error'开头的error.message
+      /^Script error\.?$/,       // 正则表达式匹配error.message
+      (msg, error) => {
+        return msg.includes('example-error');
+      },
+    ],
+    // 过滤资源或API
+    resource: [
+      'https://example.com/',    // 以'https://example.com/'开头的resource
+      /localhost/i,
+      (url) => {
+        return url.includes('example-resource');
+      },
+    ],
+    // 过滤视图
+    view: [
+      '/internal/',              // 过滤内部页面
+    ],
+  },
+});
+```
+
+## properties 配置
+
+Properties是RUM提供的自定义属性，可为任何上报事件配置该属性。
+
+| 参数 | 类型 | 描述 | 是否必填 |
+|------|------|------|----------|
+| [key: string] | string \| number | • key必须是符合JSON规范的字符串，key的最大长度为50字符，key超出部分会被截断<br/>• value为string时，最大长度为2000字符。value为非string\|number时，该键值对会被移除 | 否 |
+
+### 使用说明
+
+- 使用`evaluateApi`、`sendCustom`、`sendException`、`sendResource`等可以单独为某个事件增加properties，仅对单个事件生效
+- 全局properties和事件properties在存储时会进行合并
+- 事件properties优先级高于全局properties，合并时相同的key，事件properties会覆盖全局properties
+- 合并后properties键值对数量不可超过20对，超出会基于key进行排序后移除
+
+### 示例
+
+全局配置properties时，所有上报的事件都会拥有：
+
+```typescript
+armsRum.init({
+  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,
+  },
+});
+```
+
+为单个事件添加properties：
+
+```typescript
+// 自定义业务事件
+armsRum.sendCustom({
+  type: 'order_placed',
+  name: 'OrderEvent',
+  value: 1,
+  properties: {
+    order_id: 'ORD-12345',
+    amount: 99.99,
+  },
+});
+
+// 自定义异常
+armsRum.sendException({
+  name: 'CustomError',
+  message: 'Something went wrong',
+  properties: {
+    error_code: 'E001',
+    module: 'payment',
+  },
+});
+```
+
+## 其他配置
+
+RUM SDK支持配置基于IP和UserAgent等解析所得到的公共属性，主动配置字段优先级高于自动解析。
+
+| 参数 | 类型 | 描述 | 是否必填 |
+|------|------|------|----------|
+| device | object | 设备信息 | 否 |
+| os | object | 系统、容器信息 | 否 |
+| geo | object | 行政地理信息 | 否 |
+| isp | object | 运营商信息 | 否 |
+| net | object | 网络信息 | 否 |
+
+以上字段具体可配置项请参考日志数据说明中[公共属性](https://help.aliyun.com/zh/arms/user-experience-monitoring/log-data-description)部分。
+
+### 示例
+
+```typescript
+armsRum.init({
+  endpoint: '<your-endpoint>',
+  geo: {
+    country: 'China',
+    province: 'Zhejiang',
+    city: 'Hangzhou',
+  },
+  net: {
+    type: 'wifi',
+  },
+});
+```
+
+## beforeReport 钩子
+
+在事件上报前进行修改或过滤：
+
+```typescript
+armsRum.init({
+  endpoint: '<your-endpoint>',
+  beforeReport(event) {
+    // 返回修改后的event
+    // 返回false则丢弃该事件
+    if (event.type === 'resource' && event.url?.includes('test')) {
+      return false; // 丢弃测试资源事件
+    }
+
+    // 添加自定义属性
+    if (event.properties) {
+      event.properties.custom_field = 'custom_value';
+    }
+
+    return event;
+  },
+});
+```
+
+## 完整配置示例
+
+```typescript
+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',
+    app_version: '1.0.0',
+  },
+
+  // 上报配置
+  reportConfig: {
+    flushTime: 5000,
+    maxEventCount: 30,
+  },
+
+  // Session配置
+  sessionConfig: {
+    sampleRate: 1,
+    maxDuration: 86400000,
+    overtime: 3600000,
+  },
+
+  // 上报前钩子
+  beforeReport(event) {
+    return event;
+  },
+
+  // 自定义API解析
+  evaluateApi: async (request, response, error) => {
+    return {
+      name: request?.url || 'unknown',
+      success: error ? 0 : 1,
+      duration: response?.duration || 0,
+    };
+  },
+});
+```
+
+## SDK API
+
+RUM SDK开放API，用于修改上报自定义数据、动态修改SDK配置等。
+
+### getConfig()
+
+获取当前SDK配置对象。
+
+```typescript
+const config = armsRum.getConfig();
+console.log(config);
+```
+
+### setConfig(key, value) / setConfig(config)
+
+动态更新SDK配置。
+
+```typescript
+// 单个配置更新
+armsRum.setConfig('version', '1.2.0');
+armsRum.setConfig('env', 'pre');
+
+// 批量配置更新
+const currentConfig = armsRum.getConfig();
+armsRum.setConfig({
+  ...currentConfig,
+  version: '1.2.0',
+  env: 'pre',
+});
+```
+
+### sendCustom(payload)
+
+上报自定义业务数据，必须包含`type`、`name`和`value`三个属性，否则无法上报。
+
+| 参数 | 类型 | 描述 | 是否必填 |
+|------|------|------|----------|
+| type | string | 类型 | 是 |
+| name | string | 名称 | 是 |
+| group | string | 分组 | 否 |
+| value | number | 值 | 是 |
+| properties | object | 自定义属性 | 否 |
+
+```typescript
+armsRum.sendCustom({
+  // 必选
+  type: 'CustomEventType1',
+  name: 'customEventName2',
+  value: 111.11,
+  // 可选
+  group: 'customEventGroup3',
+  properties: {
+    prop_msg: 'custom msg',
+    prop_num: 1,
+  },
+});
+```
+
+### sendException(payload | Error)
+
+上报自定义异常数据。可以直接传入Error对象，或传入包含以下属性的对象：
+
+| 参数 | 类型 | 描述 | 是否必填 |
+|------|------|------|----------|
+| name | string | 异常名称 | 是 |
+| message | string | 异常信息 | 是 |
+| file | string | 异常发生文件 | 否 |
+| stack | string | 异常堆栈信息 | 否 |
+| line | number | 异常发生的行数 | 否 |
+| column | number | 异常发生的列数 | 否 |
+| properties | object | 自定义属性 | 否 |
+
+```typescript
+// 方式一：传入Error对象
+try {
+  // 业务逻辑
+} catch (error) {
+  armsRum.sendException(error);
+}
+
+// 方式二：传入自定义对象
+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(payload)
+
+上报自定义资源，必须包含`name`、`type`和`duration`三个属性，否则无法上报。
+
+| 参数 | 类型 | 描述 | 是否必填 |
+|------|------|------|----------|
+| name | string | 资源名 | 是 |
+| type | string | 资源类型，例如：css、javascript、xmlhttprequest、fetch、api、image、font、other | 是 |
+| duration | number | 请求耗时（毫秒） | 是 |
+| success | number | 请求成功状态：<br/>• 1：成功<br/>• 0：失败<br/>• -1：未知 | 否 |
+| method | string | 请求方法 | 否 |
+| status_code | number \| string | 请求状态码 | 否 |
+| message | string | 请求消息 | 否 |
+| url | string | 请求地址 | 否 |
+| trace_id | string | 链路追踪ID | 否 |
+| properties | object | 自定义属性 | 否 |
+
+```typescript
+armsRum.sendResource({
+  // 以下必选
+  name: 'getListByPage',
+  type: 'api',
+  duration: 800,
+  // 以下可选
+  url: 'https://www.aliyun.com/data/getListByPage',
+  success: 1,
+  method: 'GET',
+  status_code: 200,
+  properties: {
+    prop_msg: 'custom msg',
+    prop_num: 1,
+  },
+});
+```
+
+### sendView(payload)
+
+上报自定义视图事件。当`type`为`custom`时，必须包含`t1`、`t2`、`t3`中至少一个自定义性能指标，否则无法上报。
+
+| 参数 | 类型 | 描述 | 是否必填 |
+|------|------|------|----------|
+| type | string | 视图类型：`pv`（页面浏览）、`perf`（性能指标）、`webvitals`、`custom`（自定义指标）| 是 |
+| t1 | number | 自定义性能指标1（type为`custom`时至少需要t1/t2/t3之一） | 否 |
+| t2 | number | 自定义性能指标2 | 否 |
+| t3 | number | 自定义性能指标3 | 否 |
+| properties | object | 自定义属性 | 否 |
+
+```typescript
+// 上报自定义性能指标
+armsRum.sendView({
+  type: 'custom',
+  t1: 1500,
+  properties: {
+    page_type: 'home',
+  },
+});
+
+// 上报页面浏览事件
+armsRum.sendView({
+  type: 'pv',
+  properties: {
+    page_type: 'detail',
+  },
+});
+```
+
+### sendEvent(payload)
+
+上报通用自定义事件。
+
+```typescript
+armsRum.sendEvent({
+  type: 'custom_event',
+  name: 'ButtonClick',
+  properties: {
+    button_id: 'submit_btn',
+  },
+});
+```
+
+### startTrackingViews(navigationRef)
+
+启动页面导航追踪，需要传入React Navigation的navigation引用。
+
+```typescript
+import { useNavigationContainerRef } from '@react-navigation/native';
+
+const navigationContainerRef = useNavigationContainerRef();
+armsRum.startTrackingViews(navigationContainerRef.current);
+```
+
+### stopTrackingViews()
+
+停止页面导航追踪。
+
+```typescript
+armsRum.stopTrackingViews();
+```

package/docs/SDK /347/211/210/346/234/254/350/257/264/346/230/216.md"

@@ -0,0 +1,12 @@
+# SDK版本说明
+
+本文主要介绍了ARMS用户体验监控React Native SDK的版本更新历史。
+
+## 版本列表
+
+| 版本 | 发布时间 | 发布说明 |
+|------|----------|----------|
+| v0.1.3 | 2026年07月 | 原生崩溃采集安全加固与自监控系统集成：<br/>• 修复 Android/iOS 原生崩溃采集多项安全漏洞（缓冲区溢出、路径遍历、crash_id 校验）<br/>• 提升采集稳定性（栈帧上限 256、线程安全、多格式时间戳解析）<br/>• 集成 rum-core Telemetry 自监控，SDK 内部异常自动上报<br/>• 公开导出 logger、callMonitored 供用户扩展使用 |
+| v0.1.2 | 2026年05月12日 | 包名正式化与核心采集能力修复：<br/>•  rum-core 升级至 >=0.1.4，包管理迁移至 Yarn 3 workspaces<br/>• 修复 PV 路由采集（首屏丢失、无 path 路由过滤、navigationRef 时序）<br/>• 修复 API 监控默认配置误关闭、propagatorTypes 空值崩溃<br/>• Reporter AppState 回调 this 绑定修复<br/>• 完善 README、接入指南、配置参考等文档 |
+| v0.1.1 | 2025年11月28日 | React Native SDK首个正式版本，提供各种配置、API，并提供了以下采集能力：<br/>• API监控（XMLHttpRequest / fetch），包括链路追踪等特性的支持<br/>• 异常监控（JS Error、Promise Rejection、console.error）<br/>• Session相关功能（采样、超时管理）<br/>• 自定义上报（Custom、Exception、Resource、View、Event）<br/>• React Navigation集成支持 |
+| v0.1.0 | 2025年08月20日 | React Native首个版本，提供各种配置、API，并提供了以下采集能力：<br/>• API监控（XMLHttpRequest / fetch），包括链路追踪等特性的支持<br/>• 异常监控（JS Error、Promise Rejection、console.error）<br/>• Session相关功能（采样、超时管理）<br/>• 自定义上报（Custom、Exception、Resource、View、Event）<br/>• React Navigation集成支持 |