XuqmGroup-RNSDK/packages/bugcollect

@xuqm/rn-bugcollect

JS 错误、业务日志、API 异常和漏斗采集模块。它依赖 @xuqm/rn-common 获取远程配置和当前会话，不提供独立初始化或登录入口。

安装

pnpm add @xuqm/rn-common @xuqm/rn-bugcollect \
  @react-native-async-storage/async-storage

使用

import { BugCollect } from '@xuqm/rn-bugcollect'

BugCollect.setEnvironment(__DEV__ ? 'development' : 'production')
BugCollect.event('page_view', { page: 'home' })

try {
  // business
} catch (error) {
  BugCollect.captureError(error)
}

初始化只由 common 自动完成，登录只由 XuqmSDK.login() 完成。宿主通过 XuqmSDK.setPrivacyConsent(true) 同步已取得的隐私同意；只有平台启用、用户同意且 非 Debug 三个条件同时满足时，SDK 才自动注册采集。不存在宿主手工启动入口。 BugCollect.flush() 可在 App 转入后台前主动刷新队列；Debug 开发页使用 BugCollect.sendTestErrorAndFlush() 做一次性真实上报验证。

错误指纹使用 common 的统一 SHA-256 实现，事件里的 SDK 版本直接读取当前发布包版本，不再维护第二份硬编码版本号。

SourceMap 上传使用独立打包后处理流程；不要再叠加基于 Metro customSerializer 的旧插件方案，以免破坏新版 Metro 的 exports 与序列化流程。

fatal/error 持久队列复用 common 的 AES-GCM 沙箱加密能力，并在设备首次需要持久化时 使用系统安全随机源生成 256 位本地密钥。该密钥仅保存在当前应用沙箱，不来自 .xuqmconfig、不打入 Bundle/安装包，也不进入日志或上报数据；安全随机源或存储不可用 时直接放弃持久化，绝不降级写入包含堆栈和设备信息的明文。密钥丢失、格式损坏或应用 上下文不匹配时清除不可解密队列。

服务端返回 429/BUGCOLLECT_RATE_LIMITED 时，SDK 读取标准 Retry-After 并进入 最长一小时的上传冷却；队列保持不变，冷却期间不重复请求，也不会把限流异常抛给宿主 业务线程。

Issue 只有在错误堆栈能唯一匹配当前原生 Bundle state/manifest 时才携带 buildId/moduleId/moduleVersion/bundleHash 并标记 symbolicationStatus=exact；无法归属时明确为 unavailable，服务端不得猜测 latest Source Map。