跳到正文Skip to Content
快速开始React Native SDK

React Native SDK 快速开始

React Native 端 SDK。覆盖日志、埋点、性能 metric、崩溃捕获（同步异常 + 未处理 Promise rejection）、 离线持久化。要求 RN 0.72+ 与 Hermes 引擎（未处理 rejection 捕获依赖 Hermes）。

对应 SDK：sdks/react-native · 示例：examples/rn-demo · 设计：docs/07-design/sdk-react-native.md

从源码接入（当前分发方式）

当前 @argus/sdk-react-native 是仓库内的 private workspace 包, 尚未发布到公共 npm. 本指南适用于有仓库访问权限的源码集成, 不能直接按公共包名安装. 集成到已有应用时, 需要 RN 0.72+ / Hermes 宿主工程. 也可先运行仓库内基于 RN 0.76.5 / Hermes 的 Android/iOS 示例, 再将接入代码迁入自己的应用.

先在 Argus 仓库根目录安装锁定依赖并构建 SDK. 下列两个路径换成你本机的绝对路径, ARGUS_REPO 在启动 Metro 的同一终端保持有效:

export ARGUS_REPO="/absolute/path/to/x-argus"
export RN_APP="/absolute/path/to/your-rn-app"
cd "$ARGUS_REPO"
npm ci
npm run build --workspace @argus/sdk-react-native
cd "$RN_APP"
npm install --install-links=false "$ARGUS_REPO/sdks/react-native"
npm install @react-native-async-storage/async-storage
cd ios && pod install && cd ..   # 仅 iOS 需要, 为 AsyncStorage 安装原生依赖

本地 SDK 是符号链接, 必须保留源码目录及构建后的 dist/. 将下面配置合并到宿主已有的 metro.config.js, 保留项目自己的转换器和解析规则. watchFolders 让 Metro 看见链接目标; SDK 的运行依赖已内联到 bundle, 不需要把整个 Argus 仓库的 node_modules 加入宿主解析路径.

const path = require("node:path");
const { getDefaultConfig, mergeConfig } = require("@react-native/metro-config");
 
if (!process.env.ARGUS_REPO) {
  throw new Error("Set ARGUS_REPO to your x-argus checkout before starting Metro.");
}
const config = {
  watchFolders: [path.resolve(process.env.ARGUS_REPO, "sdks/react-native")],
};
module.exports = mergeConfig(getDefaultConfig(__dirname), config);

重启 Metro 后继续初始化; 修改 SDK 源码后需重新执行上面的 SDK build. 团队或构建机也需准备相同源码依赖, 本地路径不是可公开分发的版本坐标. 相关规则见 npm 本地目录安装  与 Metro 链接目录配置 .

初始化（应用入口，只调一次）

import { Platform } from "react-native";
import AsyncStorage from "@react-native-async-storage/async-storage";
import { Argus } from "@argus/sdk-react-native";
 
Argus.init({
  // 换成你在 Argus Console 拿到的 DSN
  dsn: "argus://demo-public:demo-secret@localhost:4318/demo",
  userId: "demo-user",
  appVersion: "1.0.0",
  // 宿主注入：SDK 自身不 import react-native / AsyncStorage（保持纯 JS、可 node 测）
  deviceOs: Platform.OS,
  deviceOsVersion: String(Platform.Version),
  storage: AsyncStorage,
  // 自动捕获未处理同步异常（ErrorUtils，默认 true）
  captureUncaught: true,
  // opt-in：捕获未处理 Promise rejection（Hermes，默认 false）
  captureUnhandledRejections: true,
});

上报

// 日志 → /v1/events
Argus.log("INFO", "button: log tapped", { screen: "demo" });
 
// 埋点 → /v1/events（channel=track；先设归因，再 track）
Argus.setAttribution({ utm_source: "demo", utm_medium: "app", utm_campaign: "rn" });
Argus.track("demo_button_tap", { kind: "track" });
 
// 性能 metric → /v1/events（channel=apm）
Argus.metric("button_latency", 42, { unit: "ms" });
 
// 手动 captureCrash → /v1/events
Argus.captureCrash({
  errorType: "DemoError",
  errorMessage: "manual crash from demo",
  stacktrace: new Error("demo").stack,
});
 
// 退后台时建议调用
await Argus.flush();

接入要点

  • 宿主注入：deviceOs / deviceOsVersion / storage 由你的 app 注入（SDK 不 import RN）。
  • 自动捕获：captureUncaught（默认 true，ErrorUtils 同步异常）；captureUnhandledRejections （默认 false，opt-in，Hermes 异步 rejection）。
  • 离线可靠性：注入 storage 后，离线时统一事件批次持久化，app 重启自动恢复重发 （包括日志、崩溃、埋点和性能指标）。
  • 退后台 flush：在 AppState 变为 'background' 时调 Argus.flush()，避免丢未发批次。

可运行示例 examples/rn-demo 包含 Android/iOS 宿主工程、Metro 配置和锁文件. 按示例 README 的“从仓库构建”步骤启动, 可在页面初始化 SDK, 记录日志、埋点、性能指标和模拟 Crash, 并发送或重试待处理事件. 示例的原生宿主不等于 SDK 已提供完整 native crash/ANR/OOM/APM bridge; 模拟 Crash 按钮不会主动使应用崩溃, 发送完成提示也不代表服务端已经入库. 验证上报结果时, 请到同一项目的 Console 按示例 marker 查询. 接入自己的应用仍按上面的源码接入步骤配置, 宿主环境见 React Native 官方环境指引 .

Flutter SDKGo 后端 SDK