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

package/README.md

@@ -1,39 +1,423 @@
-# rum-sdk-reactnative
+# @arms/rum-reactnative
 
-Aliyun RUM SDK For ReactNative
+阿里云ARMS用户体验监控React Native SDK，用于在React Native应用中采集前端性能、异常及用户行为数据，并上报至ARMS控制台。
 
-## Installation
+## 功能特性
 
+- **API性能监控** — 自动拦截 XMLHttpRequest / fetch 请求，采集耗时、状态码等指标
+- **JS错误捕获** — 自动捕获 JavaScript 运行时异常
+- **控制台错误监听** — 监听 `console.error` 输出
+- **链路追踪** — 支持多种传播协议的分布式链路追踪
+- **页面导航追踪** — 集成 React Navigation，自动追踪页面切换
+- **自定义事件上报** — 支持自定义业务数据、异常、资源、视图等事件上报
+- **Session管理** — 自动管理用户会话，支持采样率和超时配置
+
+## 安装
 
 ```sh
 npm install @arms/rum-reactnative
 ```
 
+> 自 `0.1.3` 起，SDK 内置原生持久化实现（iOS `NSUserDefaults` / Android `SharedPreferences`），不再依赖 `@react-native-async-storage/async-storage`，无需额外安装。详见下方 [存储说明](#存储说明)。
+
+SDK 包含原生崩溃采集模块（iOS：ObjC++ + KSCrash；Android：C/C++ + CMake），安装后**必须重新构建原生工程**，否则会报 TurboModule 方法缺失：
+
+- **iOS（bare workflow）**：`cd ios && pod install`，再在 Xcode 重新 Build。
+- **Android（bare workflow）**：Gradle Sync 后重新 Build。
+- **Expo**：`expo prebuild --clean` 后再 `expo run:ios` / `expo run:android`。
+
+> **原生编译环境**：Android 需安装 NDK 与 CMake（可在 Android Studio 的 SDK Manager 中安装），iOS 需 CocoaPods（`pod install` 时自动拉取并编译 KSCrash）。由于崩溃采集模块以源码方式编译，首次构建耗时会略有增加，后续增量构建不受影响。
+
+
+## 快速开始
+
+在应用入口处初始化SDK：
+
+```ts
+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 链路追踪
+
+支持布尔值开关或详细配置对象：
+
+```ts
+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 事件过滤
+
+```ts
+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配置。
+
+```ts
+// 单个配置更新
+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 回调模式**
+
+```tsx
+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 模式（推荐）**
+
+```tsx
+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>
+  );
+}
+```
+
+## Expo 接入
+
+SDK 提供一个零依赖的 Expo config plugin，便于在 Expo 工程中通过 `app.config` 声明 SDK 配置，避免在 JS 入口硬编码 `endpoint`。
+
+在 `app.config.ts` 中：
+
+```ts
+const config = {
+  expo: {
+    plugins: [
+      ['@arms/rum-reactnative', { endpoint: '<your-endpoint>', env: 'prod' }],
+    ],
+  },
+};
+export default config;
+```
+
+随后照常 `expo prebuild` / EAS Build。运行时通过 `Constants.expoConfig?.extra?.rumSdk` 读取该配置：
+
+```ts
+import { Constants } from 'expo-constants';
+import armsRum from '@arms/rum-reactnative';
+
+const cfg = (Constants.expoConfig?.extra as any)?.rumSdk;
+armsRum.init({ endpoint: cfg?.endpoint, env: cfg?.env });
+```
+
+> 即便不使用 config plugin，Expo 工程在 `npm install` 后执行 `expo prebuild --clean` 即可由 autolinking 自动接入原生模块；plugin 仅提供配置透传的便利。
+
+## 原生代码集成方式
+
+SDK 的原生崩溃采集层通过**源码编译**集成，不预编译二进制随 npm 包发布：
+
+- **iOS**：KSCrash 通过 CocoaPods 源码依赖（`s.dependency "KSCrash"`）引入，`pod install` 时自动编译。
+- **Android**：`librum_crash.so` 由宿主工程 Gradle 通过 `externalNativeBuild`（CMake）在构建时编译，需 NDK / CMake（RN 工程通常已具备）。
+
+原生模块会在宿主工程构建时自动编译，无需额外的预编译产物或手动步骤。
+
+### 自定义API解析（evaluateApi）
+
+当默认的API事件解析逻辑不满足需求时，可通过 `evaluateApi` 自定义解析。函数接收以下参数：
+
+- **request** — 请求信息
+- **response** — 响应信息
+- **error** — 错误信息
+- **xhr** — 原始XHR对象
+
+返回值为 `IApiBaseAttr` 对象：
+
+```ts
+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' }),
+    };
+  }
+});
+```
+
+### 自定义事件上报示例
+
+```ts
+// 自定义业务事件
+armsRum.sendCustom({
+  name: 'order_placed',
+  properties: { order_id: 'ORD-12345', amount: 99.99 }
+});
+
+// 手动上报异常
+try {
+  // 业务逻辑
+} catch (error) {
+  armsRum.sendException(error);
+}
+```
+
+### beforeReport 钩子
+
+在事件上报前进行修改或过滤：
 
-## Usage
+```ts
+armsRum.init({
+  beforeReport(event) {
+    // 返回修改后的event，返回 false 则丢弃该事件
+    return event;
+  }
+});
+```
 
+## 完整配置示例
 
 ```ts
 import armsRum from '@arms/rum-reactnative';
 
 armsRum.init({
-  pid: '${pid}',
-  endpoint: '${endpoint}',
-  // 设置环境信息，参考值：'prod' | 'gray' | 'pre' | 'daily' | 'local'
+  // 基础配置
+  endpoint: '<your-endpoint>',
   env: 'prod',
+  version: '1.0.0',
+
+  // 用户配置
+  user: {
+    name: 'zhangsan',
+    tags: 'vip',
+  },
+
+  // 采集器配置
   collectors: {
     api: true,
-    // JS错误监听开关，默认开启
     jsError: true,
-    // 控制台错误监听开关，默认开启
-    consoleError: 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/],
   },
-  // 链路追踪配置开关，默认关闭
-  tracing: false,
-});
 
+  // 全局自定义属性
+  properties: {
+    channel: 'appstore',
+  },
+
+  // 上报配置
+  reportConfig: {
+    flushTime: 5000,
+    maxEventCount: 30,
+  },
+
+  // Session配置
+  sessionConfig: {
+    sampleRate: 1,
+    maxDuration: 86400000,
+    overtime: 3600000,
+  },
+
+  // 上报前钩子
+  beforeReport(event) {
+    return event;
+  },
+});
 ```
 
-## Help
-https://help.aliyun.com/zh/arms/user-experience-monitoring/
+## 存储说明
+
+SDK 仅持久化一个键 `_arms_uid`（匿名用户 UID），用于跨冷启动保持 UV 稳定。底层采用各平台原生轻量级 KV 存储：
+
+| 平台 | 实现 | 命名空间 |
+|------|------|----------|
+| iOS | `NSUserDefaults`（独立 suite） | `com.aliyun.arms.rum.reactnative` |
+| Android | `SharedPreferences`（独立 prefs 文件） | `com.aliyun.arms.rum.reactnative` |
+
+### 原生存储 API
+
+原生模块提供以下能力（全部为异步 Promise，且仅作用于上表的独立命名空间，不会读写宿主 App 的偏好数据）：
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `getItem(key)` | `Promise<string \| null>` | 读取字符串值，不存在返回 `null` |
+| `setItem(key, value)` | `Promise<void>` | 写入字符串值 |
+| `removeItem(key)` | `Promise<void>` | 删除指定 key |
+| `clear()` | `Promise<void>` | 清空 SDK 命名空间下的所有 key |
+| `getAllKeys()` | `Promise<string[]>` | 列出 SDK 命名空间下的所有 key |
+
+> 该原生模块主要服务于 SDK 内部，不属于公开 API；如有定制场景需要直接调用，可从 `@arms/rum-reactnative` 内部模块引入，**未来版本可能调整签名**。
+
+### 升级 / 接入注意事项
+
+1. **必须重新构建原生工程**：新增了 TurboModule 方法，升级或首次接入后需要重新执行 iOS 的 `pod install`、Android 的 Gradle Sync；Expo 工程请执行 `expo prebuild --clean` 后再编译，否则会报 protocol method 缺失。
+2. **隔离命名空间，不污染宿主 App**：iOS 走独立 `NSUserDefaults` suite、Android 走独立 prefs 文件，与宿主 App 自身的偏好数据互不干扰；用户卸载 / 抹机时会一并清除。
+3. **从旧版本（依赖 AsyncStorage）升级会重置一次 UID**：原 AsyncStorage 中的 `_arms_uid` 不会自动迁移到新存储，老用户首次升级后会被分配新 UID（仅影响一次 UV 统计的连续性，不影响功能与后续使用）。如对历史 UID 连续性有强诉求，请提 issue。
+
+## 相关文档
 
+- [ARMS用户体验监控文档](https://help.aliyun.com/zh/arms/user-experience-monitoring/)

package/RumSdkReactnative.podspec

@@ -0,0 +1,28 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "RumSdkReactnative"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://code.alibaba-inc.com/aliyun-rum/rum-sdk-reactnative.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,c,cpp}"
+  s.private_header_files = "ios/**/*.h"
+
+  s.resource_bundles = {
+    "RumSdkReactnativePrivacy" => ["ios/PrivacyInfo.xcprivacy"]
+  }
+
+  # KSCrash 通过 CocoaPods 源码依赖引入。KSCrash 不发布官方 XCFramework，
+  # 故不自行预编译，直接由宿主工程 `pod install` 时源码编译。
+  s.dependency "KSCrash", "~> 2.0"
+
+  install_modules_dependencies(s)
+end

package/android/build.gradle

@@ -0,0 +1,83 @@
+ext.getExtOrDefault = {name ->
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties['RumSdkReactnative_' + name]
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+apply plugin: "com.facebook.react"
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["RumSdkReactnative_" + name]).toInteger()
+}
+
+android {
+  namespace "com.rumsdkreactnative"
+
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+
+    ndk {
+      abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
+    }
+
+    // librum_crash.so 由宿主工程构建时通过 CMake 源码编译，不预编译随 npm 包发布。
+    // 显式指定 c++_shared STL：rum_test_crash.cpp 使用 C++ 异常（<stdexcept>），
+    // 精简的 system STL 不支持。RN 工程本身即依赖 c++_shared。
+    externalNativeBuild {
+      cmake {
+        cFlags "-fno-omit-frame-pointer", "-Wno-format"
+        arguments "-DANDROID_STL=c++_shared"
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "src/main/jni/CMakeLists.txt"
+    }
+  }
+
+  buildFeatures {
+    buildConfig true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lintOptions {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+
+  sourceSets {
+    main {
+      java.srcDirs += [
+        "generated/java",
+        "generated/jni"
+      ]
+    }
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+def kotlin_version = getExtOrDefault("kotlinVersion")
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+}

package/android/gradle.properties

@@ -0,0 +1,6 @@
+RumSdkReactnative_kotlinVersion=2.0.21
+RumSdkReactnative_minSdkVersion=24
+RumSdkReactnative_targetSdkVersion=34
+RumSdkReactnative_compileSdkVersion=35
+# NDK 版本由宿主 App 决定；SDK 自身不强制特定 NDK，使用宿主已安装的版本即可。
+

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,13 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <application>
+    <!--
+      崩溃处理器自启动：通过 ContentProvider 在 Application.onCreate() 之前安装
+      Thread.UncaughtExceptionHandler，无需宿主 App 显式调用 SDK 初始化方法。
+    -->
+    <provider
+      android:name="com.rumsdkreactnative.crash.CrashInitProvider"
+      android:authorities="${applicationId}.rum-crash-init"
+      android:exported="false"
+      android:initOrder="100" />
+  </application>
+</manifest>