XuqmGroup-RNSDK/packages/bugcollect

@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']

工作原理

1. LogQueue：事件先进入内存队列，按批次异步上传到 bugCollectApiUrl
2. ErrorCapture：startCapture() 注册全局 ErrorUtils handler，自动捕获未处理异常
3. Fingerprint：为每个错误生成指纹（基于 message + stack），用于服务端去重聚合
4. FunnelTracker：客户端维护漏斗进度，服务端跨 session 聚合

配置

bugCollectApiUrl 和 bugCollectEnabled 由 @xuqm/rn-common 在 init 后从 /api/sdk/config 自动获取，无需 App 传入。