129 行
3.4 KiB
Markdown
129 行
3.4 KiB
Markdown
|
# BugCollect
|
||
|
|
|
||
|
|
`@xuqm/rn-bugcollect` 用于采集 JS 异常、原生崩溃、业务面包屑和自定义事件。它共享
|
||
|
|
Common 的自动配置与会话，不提供第二套初始化或登录入口。
|
||
|
|
|
||
|
|
## 安装
|
||
|
|
|
||
|
|
```bash
|
||
|
|
pnpm add @xuqm/rn-bugcollect @xuqm/rn-common
|
||
|
|
```
|
||
|
|
|
||
|
|
完成 [自动配置](./setup) 后无需在 App 入口调用 BugCollect 初始化方法。
|
||
|
|
|
||
|
|
## 隐私前置条件
|
||
|
|
|
||
|
|
只有宿主明确同步用户授权后才允许采集：
|
||
|
|
|
||
|
|
```ts
|
||
|
|
import { XuqmSDK } from '@xuqm/rn-common'
|
||
|
|
|
||
|
|
await XuqmSDK.setPrivacyConsent(true)
|
||
|
|
```
|
||
|
|
|
||
|
|
撤回授权：
|
||
|
|
|
||
|
|
```ts
|
||
|
|
await XuqmSDK.setPrivacyConsent(false)
|
||
|
|
```
|
||
|
|
|
||
|
|
SDK 不负责展示隐私声明，也不会把一次历史授权永久推断为当前授权。
|
||
|
|
|
||
|
|
## 自动采集
|
||
|
|
|
||
|
|
满足以下条件时，Release 应用自动启用异常采集：
|
||
|
|
|
||
|
|
- 租户平台已开启 BugCollect。
|
||
|
|
- 当前配置有效。
|
||
|
|
- 用户已同意隐私声明。
|
||
|
|
- App 构建没有使用应急关闭选项。
|
||
|
|
|
||
|
|
服务关闭、网络失败、限流或上传失败不会阻断宿主业务。服务端明确返回关闭状态后，SDK 会
|
||
|
|
停止后续采集，直到获取到新的有效平台配置。
|
||
|
|
|
||
|
|
## 手动记录
|
||
|
|
|
||
|
|
```ts
|
||
|
|
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。
|
||
|
|
|
||
|
|
## 自定义事件与漏斗
|
||
|
|
|
||
|
|
```ts
|
||
|
|
BugCollect.event('checkout_started', {
|
||
|
|
source: 'cart',
|
||
|
|
})
|
||
|
|
|
||
|
|
BugCollect.defineFunnel({
|
||
|
|
id: 'checkout',
|
||
|
|
steps: ['checkout_started', 'payment_started', 'payment_completed'],
|
||
|
|
})
|
||
|
|
|
||
|
|
const progress = BugCollect.getFunnelProgress('checkout')
|
||
|
|
```
|
||
|
|
|
||
|
|
事件名应保持稳定，属性只记录分析所需的非敏感枚举和数值。
|
||
|
|
|
||
|
|
## 日志级别与环境
|
||
|
|
|
||
|
|
```ts
|
||
|
|
BugCollect.setLogLevel(__DEV__ ? 'debug' : 'warn')
|
||
|
|
BugCollect.setEnvironment(__DEV__ ? 'development' : 'production')
|
||
|
|
BugCollect.setSampleRate(0.2)
|
||
|
|
```
|
||
|
|
|
||
|
|
采样率只影响非致命事件，致命异常不参与客户端采样。线上采样与服务端限流共同生效，宿主
|
||
|
|
不需要自行实现重试队列。
|
||
|
|
|
||
|
|
## Debug 验证
|
||
|
|
|
||
|
|
Debug 默认不自动上传。开发者工具页可以在用户已同意隐私声明后显式执行：
|
||
|
|
|
||
|
|
```ts
|
||
|
|
await BugCollect.sendTestErrorAndFlush('BugCollect integration test')
|
||
|
|
```
|
||
|
|
|
||
|
|
该方法用于验证配置和上传链路，不应放在正常业务流程中。
|
||
|
|
|
||
|
|
## 主动刷新
|
||
|
|
|
||
|
|
```ts
|
||
|
|
await BugCollect.flush()
|
||
|
|
```
|
||
|
|
|
||
|
|
通常不需要主动调用。应用即将退出且确实需要等待当前队列时才使用；上传失败仍应当允许
|
||
|
|
宿主继续退出。
|
||
|
|
|
||
|
|
## 应急关闭
|
||
|
|
|
||
|
|
当 BugCollect 服务不可用且影响生产打包时，宿主可以通过自己的 Release 构建参数关闭本次
|
||
|
|
构建的 BugCollect。该设置只用于应急，不写入平台下发配置，也不允许业务页面在运行时
|
||
|
|
反向开启平台已关闭的服务。
|
||
|
|
|
||
|
|
## 数据与错误边界
|
||
|
|
|
||
|
|
- SDK 会对常见敏感字段进行脱敏，但调用方仍须避免主动传入敏感正文。
|
||
|
|
- 网络和上传错误不会抛到全局导致 App 崩溃。
|
||
|
|
- 未授权、服务关闭和配置不可用时，自定义记录调用安全跳过。
|
||
|
|
- `sendTestErrorAndFlush` 是诊断方法，会把错误明确返回给开发者页面。
|
