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

package/README.md

@@ -15,9 +15,20 @@
 ## 安装
 
 ```sh
-npm install @arms/rum-reactnative @react-native-async-storage/async-storage
+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：
@@ -220,6 +231,44 @@ export default function App() {
 }
 ```
 
+## 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` 自定义解析。函数接收以下参数：
@@ -340,6 +389,35 @@ armsRum.init({
 });
 ```
 
+## 存储说明
+
+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>