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

package/docs//346/216/245/345/205/245ReactNative/345/272/224/347/224/250.md

@@ -0,0 +1,238 @@
+# 接入React Native应用
+
+阿里云ARMS用户体验监控支持监控React Native应用（编译为Android和iOS等原生应用），通过集成npm包的方式，采集应用运行过程中的性能指标、异常问题和用户行为数据，并上报至ARMS控制台，帮助您提升应用的稳定性和用户体验。
+
+## 创建应用
+
+1. 登录[ARMS控制台](https://arms.console.aliyun.com/#/home)。
+2. 在左侧导航栏选择**用户体验监控** > **应用列表**，并在顶部菜单栏选择目标地域。
+3. 在**应用列表**页面单击**添加应用**。
+4. 在**创建应用**面板单击**React Native**。
+5. 在**React Native**面板上输入应用名称和描述，然后单击**创建**。
+
+   > **说明**：应用名称唯一，不能与已创建的应用名称重复。创建成功后，当前应用将会自动生成对应的`endpoint`地址。
+
+6. 记录生成的`endpoint`地址，后续初始化SDK时需要使用。
+
+## 安装SDK
+
+### 前提条件
+
+- React Native版本 >= 0.71（SDK 使用新架构 TurboModule，需 RN 0.71 及以上）
+- Node.js >= 18
+- npm或yarn包管理工具
+- Android 构建：需安装 NDK 与 CMake（由宿主工程的 `ndkVersion` 决定，SDK 不强制特定版本）
+- iOS 构建：需 CocoaPods（用于拉取 `KSCrash` 崩溃采集依赖）
+
+### 安装步骤
+
+**1. 安装 npm 包**
+
+在您的React Native项目根目录下执行：
+
+```bash
+npm install @arms/rum-reactnative
+```
+
+或使用yarn：
+
+```bash
+yarn add @arms/rum-reactnative
+```
+
+> **说明**：自 `0.1.3` 起，SDK 内置原生存储（iOS `NSUserDefaults` / Android `SharedPreferences`），不再依赖 `@react-native-async-storage/async-storage`，无需额外安装。
+
+**2. 重新构建原生工程**
+
+SDK 包含原生崩溃采集模块（iOS 为 ObjC++ + KSCrash，Android 为 C/C++ + CMake），安装后必须重新构建原生工程，否则会报 TurboModule 方法缺失：
+
+- **iOS**（bare workflow）：在 `ios` 目录执行 `pod install`，然后在 Xcode 重新 Build。
+- **Android**（bare workflow）：执行 Gradle Sync 后重新 Build。
+- **Expo**：执行 `expo prebuild --clean` 后再 `expo run:ios` / `expo run:android`。
+
+> **首次构建说明**：崩溃采集模块以源码方式编译（iOS 编译 `KSCrash`，Android 通过 CMake 编译 C/C++），首次构建耗时会略有增加，后续增量构建不受影响。
+
+
+## 初始化SDK
+
+推荐在应用入口处（如`App.tsx`或`index.js`）进行SDK初始化。
+
+### 基础初始化
+
+```typescript
+import armsRum from '@arms/rum-reactnative';
+
+armsRum.init({
+  endpoint: '<your-endpoint>'  // 替换为控制台获取的endpoint地址
+});
+```
+
+### 完整初始化示例
+
+```typescript
+import armsRum from '@arms/rum-reactnative';
+
+armsRum.init({
+  // 基础配置
+  endpoint: '<your-endpoint>',
+  env: 'prod',              // 环境：'prod' | 'gray' | 'pre' | 'daily' | 'local'
+  version: '1.0.0',         // 应用版本号
+
+  // 用户配置
+  user: {
+    name: 'zhangsan',       // 用户名称（建议关联业务账号）
+    tags: 'vip',            // 用户标签
+  },
+
+  // 采集器配置
+  collectors: {
+    api: true,              // API请求监控
+    jsError: true,          // JavaScript错误捕获
+    consoleError: true,     // console.error监听
+  },
+
+  // 链路追踪配置
+  tracing: {
+    enable: true,
+    sample: 0.1,            // 10%采样
+    propagatorTypes: ['tracecontext'],
+  },
+
+  // Session配置
+  sessionConfig: {
+    sampleRate: 1,          // 100%采样
+    maxDuration: 86400000,  // Session最大持续时间（24小时）
+    overtime: 3600000,      // Session超时时间（1小时）
+  },
+
+  // 上报配置
+  reportConfig: {
+    flushTime: 3000,        // 上报时间间隔（ms）
+    maxEventCount: 20,      // 单次上报最大事件数
+  },
+});
+```
+
+> **重要**：请将`endpoint`替换为您在ARMS控制台创建应用后获取的实际地址。
+
+## 集成React Navigation（可选）
+
+如果您的应用使用了[@react-navigation/native](https://reactnavigation.org/)进行路由管理，可以集成页面自动追踪功能。
+
+### 方式一：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>
+  );
+}
+```
+
+> **说明**：集成后，SDK会自动采集页面切换事件，包括页面名称、加载时间等信息。
+
+## 验证接入
+
+完成上述步骤后，启动您的React Native应用并进行一些操作（如点击按钮、发起网络请求等）。等待约1-2分钟后，在ARMS控制台的**用户体验监控** > **应用列表**中查看您的应用，确认有数据上报。
+
+您可以在控制台中查看：
+- **实时概览**：PV、UV、JS错误数、API请求数等核心指标
+- **会话详情**：用户会话轨迹、页面浏览路径
+- **异常分析**：JS错误堆栈、错误分布
+- **性能分析**：API耗时分布、慢接口TOP榜
+
+## 常见问题
+
+### 1. 如何确认SDK是否正常工作？
+
+可以在初始化后调用以下方法检查配置：
+
+```typescript
+const config = armsRum.getConfig();
+console.log('SDK Config:', config);
+```
+
+### 2. 为什么没有数据上报？
+
+请检查以下几点：
+- `endpoint`地址是否正确
+- 应用是否有网络权限
+- 是否已重新构建原生工程（`pod install` / Gradle Sync / `expo prebuild --clean`），否则原生模块不会生效
+- 查看应用日志中是否有SDK相关的错误信息
+
+### 3. 如何在调试阶段立即看到上报数据？
+
+可以将`reportConfig.flushTime`设置为0，实现立即上报：
+
+```typescript
+armsRum.init({
+  endpoint: '<your-endpoint>',
+  reportConfig: {
+    flushTime: 0,  // 立即上报
+  },
+});
+```
+
+> **注意**：生产环境不建议设置为0，会增加网络请求频率。
+
+### 4. 如何过滤不需要监控的资源或异常？
+
+使用`filters`配置进行过滤：
+
+```typescript
+armsRum.init({
+  endpoint: '<your-endpoint>',
+  filters: {
+    resource: [
+      'https://cdn.example.com/',  // 过滤特定域名的资源
+      /localhost/i,                 // 过滤本地资源
+    ],
+    exception: [
+      /^Script error/,             // 过滤Script error
+    ],
+  },
+});
+```
+
+### 5. Android 构建报错找不到 NDK 或 CMake？
+
+SDK 的 Android 崩溃采集模块通过 CMake 从源码编译，需要 NDK 与 CMake。若构建报错（如 `NDK not configured` / `CMake ... not found`），请通过 Android Studio 的 **SDK Manager** > **SDK Tools** 勾选安装 **NDK (Side by side)** 与 **CMake**；或在命令行使用 `sdkmanager` 安装。
+
+### 6. iOS `pod install` 拉取 KSCrash 失败？
+
+`KSCrash` 通过 CocoaPods 源码依赖引入。若拉取失败，先执行 `pod repo update` 更新本地 spec 仓库后重试；网络受限环境可配置 CocoaPods 镜像源。

package/ios/PrivacyInfo.xcprivacy

@@ -0,0 +1,93 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <!--
+        RUM React Native SDK Privacy Manifest
+        声明本 SDK 用于：CrashData / PerformanceData / OtherDiagnosticData
+        用途均为 35F9.1（应用功能 Diagnostics）。
+    -->
+    <key>NSPrivacyTracking</key>
+    <false/>
+    <key>NSPrivacyTrackingDomains</key>
+    <array/>
+    <key>NSPrivacyCollectedDataTypes</key>
+    <array>
+        <dict>
+            <key>NSPrivacyCollectedDataType</key>
+            <string>NSPrivacyCollectedDataTypeCrashData</string>
+            <key>NSPrivacyCollectedDataTypeLinked</key>
+            <false/>
+            <key>NSPrivacyCollectedDataTypeTracking</key>
+            <false/>
+            <key>NSPrivacyCollectedDataTypePurposes</key>
+            <array>
+                <string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
+            </array>
+        </dict>
+        <dict>
+            <key>NSPrivacyCollectedDataType</key>
+            <string>NSPrivacyCollectedDataTypePerformanceData</string>
+            <key>NSPrivacyCollectedDataTypeLinked</key>
+            <false/>
+            <key>NSPrivacyCollectedDataTypeTracking</key>
+            <false/>
+            <key>NSPrivacyCollectedDataTypePurposes</key>
+            <array>
+                <string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
+            </array>
+        </dict>
+        <dict>
+            <key>NSPrivacyCollectedDataType</key>
+            <string>NSPrivacyCollectedDataTypeOtherDiagnosticData</string>
+            <key>NSPrivacyCollectedDataTypeLinked</key>
+            <false/>
+            <key>NSPrivacyCollectedDataTypeTracking</key>
+            <false/>
+            <key>NSPrivacyCollectedDataTypePurposes</key>
+            <array>
+                <string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
+            </array>
+        </dict>
+    </array>
+    <key>NSPrivacyAccessedAPITypes</key>
+    <array>
+        <!-- 用户偏好读取（NSUserDefaults，CA92.1） -->
+        <dict>
+            <key>NSPrivacyAccessedAPIType</key>
+            <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
+            <key>NSPrivacyAccessedAPITypeReasons</key>
+            <array>
+                <string>CA92.1</string>
+            </array>
+        </dict>
+        <!-- 文件时间戳（C617.1：本 SDK 访问） -->
+        <dict>
+            <key>NSPrivacyAccessedAPIType</key>
+            <string>NSPrivacyAccessedAPICategoryFileTimestamp</string>
+            <key>NSPrivacyAccessedAPITypeReasons</key>
+            <array>
+                <string>C617.1</string>
+            </array>
+        </dict>
+        <!-- 系统启动时间（35F9.1：性能/崩溃诊断） -->
+        <dict>
+            <key>NSPrivacyAccessedAPIType</key>
+            <string>NSPrivacyAccessedAPICategorySystemBootTime</string>
+            <key>NSPrivacyAccessedAPITypeReasons</key>
+            <array>
+                <string>35F9.1</string>
+            </array>
+        </dict>
+        <!-- 磁盘空间（85F4.1：崩溃报告写入容量检查） -->
+        <dict>
+            <key>NSPrivacyAccessedAPIType</key>
+            <string>NSPrivacyAccessedAPICategoryDiskSpace</string>
+            <key>NSPrivacyAccessedAPITypeReasons</key>
+            <array>
+                <string>85F4.1</string>
+            </array>
+        </dict>
+    </array>
+</dict>
+</plist>

package/ios/RumCrashReporter.h

@@ -0,0 +1,38 @@
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * RumCrashReporter
+ *
+ * 基于 KSCrash v2 的崩溃采集封装。负责：
+ *   - 早期注册（__attribute__((constructor))）保证尽早接管 Mach/Signal/CPP/NSException
+ *   - 持久化崩溃报告到 KSCrash 默认目录，标准化为 JSON 字典数组供 JS 上报
+ *   - 维护 crash context（session/view）以便崩溃时落盘
+ */
+@interface RumCrashReporter : NSObject
+
+/** 安装 KSCrash 监控（幂等，重复调用安全） */
++ (void)install;
+
+/** 上次运行是否崩溃 */
++ (BOOL)crashedLastRun;
+
+/** 获取待上报的崩溃报告（已序列化为 NSDictionary 数组） */
++ (NSArray<NSDictionary *> *)pendingCrashReports;
+
+/** 按 crashId 删除已上报报告 */
++ (void)clearCrashReportsWithIds:(NSArray<NSString *> *)crashIds;
+
+/** 清除所有崩溃报告文件（用于清理无 crash_id 的旧版文件） */
++ (void)clearAllCrashReports;
+
+/** 清理过期和超限的崩溃文件（maxFiles 上限，maxAgeMs 过期时间） */
++ (void)cleanupOldCrashesWithMaxFiles:(NSInteger)maxFiles maxAgeMs:(double)maxAgeMs;
+
+/** 更新 crash 上下文（JSON 字符串：session_id / view_id / view_name 等） */
++ (void)updateCrashContext:(NSString *)context;
+
+@end
+
+NS_ASSUME_NONNULL_END