BugCollect

@xuqm/rn-bugcollect 用于采集 JS 异常、原生崩溃、业务面包屑和自定义事件。它共享 Common 的自动配置与会话，不提供第二套初始化或登录入口。

安装

pnpm add @xuqm/rn-bugcollect @xuqm/rn-common

完成自动配置后无需在 App 入口调用 BugCollect 初始化方法。

隐私前置条件

只有宿主明确同步用户授权后才允许采集：

import { XuqmSDK } from '@xuqm/rn-common'

await XuqmSDK.setPrivacyConsent(true)

撤回授权：

await XuqmSDK.setPrivacyConsent(false)

SDK 不负责展示隐私声明，也不会把一次历史授权永久推断为当前授权。

自动采集

满足以下条件时，Release 应用自动启用异常采集：

租户平台已开启 BugCollect。
当前配置有效。
用户已同意隐私声明。
App 构建没有使用应急关闭选项。

服务关闭、网络失败、限流或上传失败不会阻断宿主业务。服务端明确返回关闭状态后，SDK 会停止后续采集，直到获取到新的有效平台配置。

手动记录

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

BugCollect.addBreadcrumb({
  type: 'navigation',
  category: 'order',
  message: '进入订单详情',
  data: { orderType: 'outpatient' },
})

BugCollect.info('开始提交订单')
BugCollect.warn('接口响应较慢', { elapsedMs: 2200 })

try {
  await submitOrder()
} catch (error) {
  BugCollect.captureError(error, {
    scene: 'submit-order',
  })
}

不要把密码、Token、身份证号、手机号、病历正文或完整请求响应放入 metadata。

自定义事件与漏斗

BugCollect.event('checkout_started', {
  source: 'cart',
})

BugCollect.defineFunnel({
  id: 'checkout',
  steps: ['checkout_started', 'payment_started', 'payment_completed'],
})

const progress = BugCollect.getFunnelProgress('checkout')

事件名应保持稳定，属性只记录分析所需的非敏感枚举和数值。

日志级别与环境

BugCollect.setLogLevel(__DEV__ ? 'debug' : 'warn')
BugCollect.setEnvironment(__DEV__ ? 'development' : 'production')
BugCollect.setSampleRate(0.2)

采样率只影响非致命事件，致命异常不参与客户端采样。线上采样与服务端限流共同生效，宿主不需要自行实现重试队列。

Debug 验证

Debug 默认不自动上传。开发者工具页可以在用户已同意隐私声明后显式执行：

await BugCollect.sendTestErrorAndFlush('BugCollect integration test')

该方法用于验证配置和上传链路，不应放在正常业务流程中。

主动刷新

await BugCollect.flush()

通常不需要主动调用。应用即将退出且确实需要等待当前队列时才使用；上传失败仍应当允许宿主继续退出。

应急关闭

当 BugCollect 服务不可用且影响生产打包时，宿主可以通过自己的 Release 构建参数关闭本次构建的 BugCollect。该设置只用于应急，不写入平台下发配置，也不允许业务页面在运行时反向开启平台已关闭的服务。

数据与错误边界

SDK 会对常见敏感字段进行脱敏，但调用方仍须避免主动传入敏感正文。
网络和上传错误不会抛到全局导致 App 崩溃。
未授权、服务关闭和配置不可用时，自定义记录调用安全跳过。
sendTestErrorAndFlush 是诊断方法，会把错误明确返回给开发者页面。

3.4 KiB 原始文件 Blame 文件历史