76099d897e
- 将 Android SDK 的 mapping 上传端点从 /log/v1/sourcemaps/upload 更改为 /bugcollect/v1/sourcemaps/upload - 将 RN SDK 的 API 端点从 /log/v1/ 统一更改为 /bugcollect/v1/ - 在 LogQueue.ts 的请求体中添加 sentAt 时间戳和 SDK 信息 - 重构 BugCollect.ts 中的事件结构，将 appVersion 重命名为 release，添加 environment 和 sdk 字段 - 将 JS 错误上报的类型从 js_error 改为 issue，并调整错误级别分类 - 为 warn 和 info 方法添加完整的 issue 事件结构 - 在 types.ts 中添加新的数据类型定义，包括 Level、Platform、SdkInfo、ExceptionInfo 等 - 为 IssueEvent 添加详细的异常信息结构，包括类型、值和堆栈跟踪 - 添加完整的错误收集 API v1 规范审阅报告文档 - 在数据库迁移脚本中为日志表添加新字段，包括级别、环境、设备信息、SDK 信息等 |
||
|---|---|---|
| .. | ||
| metro | ||
| src | ||
| package.json | ||
| README.md | ||
| tsconfig.json | ||
@xuqm/rn-bugcollect
XuqmGroup RN SDK 错误采集模块。提供日志采集、错误追踪、漏斗分析能力。
安装
yarn add @xuqm/rn-bugcollect
Peer dependencies：@xuqm/rn-common >= 0.4.0，@react-native-async-storage/async-storage >= 1.21.0，react-native >= 0.76
快速开始
import { BugCollect } from '@xuqm/rn-bugcollect'
// 1. 设置日志级别
BugCollect.setLogLevel('debug') // 'debug' | 'info' | 'warn' | 'error'
// 2. 设置环境标签
BugCollect.setEnvironment('production') // 'development' | 'staging' | 'production'
// 3. 开启全局错误捕获（App 启动时调用一次）
BugCollect.startCapture()
// 4. 记录自定义事件
BugCollect.event('page_view', { page: 'home' })
// 5. 上报错误
try { ... } catch (e) { BugCollect.captureError(e) }
API
BugCollect 对象
| API | 说明 |
|---|---|
BugCollect.setLogLevel(level) |
设置最低日志级别（低于此级别的事件被丢弃） |
BugCollect.setEnvironment(env) |
设置环境标签（附加到每个事件） |
BugCollect.startCapture() |
开启全局 JS 错误和未处理 Promise rejection 捕获 |
BugCollect.event(name, properties?) |
记录自定义分析事件 |
BugCollect.captureError(error, metadata?) |
上报 JS 异常 |
BugCollect.warn(message, metadata?) |
记录警告（需级别允许） |
BugCollect.info(message, metadata?) |
记录信息事件（需级别允许） |
BugCollect.defineFunnel(id, steps) |
定义漏斗（按步骤顺序追踪转化） |
BugCollect.getFunnelProgress(funnelId) |
获取客户端漏斗进度 |
BugCollect.flush() |
立即刷新所有待发送事件（如 App 进后台前调用） |
事件类型
| 类型 | 说明 |
|---|---|
LogEvent |
自定义事件（type: 'event'） |
IssueEvent |
错误事件（type: 'js_error' / 'native_crash' / 'api_error' / 'warning'） |
日志级别
'debug' (0) < 'info' (1) < 'warn' (2) < 'error' (3)
漏斗分析示例
import { BugCollect } from '@xuqm/rn-bugcollect'
// 定义漏斗
BugCollect.defineFunnel('checkout', ['cart_view', 'checkout_start', 'payment_done'])
// 在业务代码中记录步骤事件（SDK 自动推进漏斗）
BugCollect.event('cart_view')
BugCollect.event('checkout_start')
BugCollect.event('payment_done')
// 查询进度
const progress = BugCollect.getFunnelProgress('checkout')
console.log(progress?.completedSteps) // ['cart_view', 'checkout_start', 'payment_done']
工作原理
- LogQueue：事件先进入内存队列，按批次异步上传到
bugCollectApiUrl - ErrorCapture：
startCapture()注册全局ErrorUtilshandler，自动捕获未处理异常 - Fingerprint：为每个错误生成指纹（基于 message + stack），用于服务端去重聚合
- FunnelTracker：客户端维护漏斗进度，服务端跨 session 聚合
配置
bugCollectApiUrl 和 bugCollectEnabled 由 @xuqm/rn-common 在 init 后从 /api/sdk/config 自动获取，无需 App 传入。
