| .. | ||
| src | ||
| build.gradle.kts | ||
| consumer-rules.pro | ||
| proguard-rules.pro | ||
| README.md | ||
sdk-bugcollect
XuqmGroup Android SDK Bug 采集模块。提供错误采集、Crash 捕获、漏斗分析能力。
服务端返回 HTTP 429 或 BUGCOLLECT_RATE_LIMITED 时，SDK 按 Retry-After 暂停后台
上传（最长一小时），保留本地队列且不向宿主业务线程抛异常。
依赖
implementation("com.xuqm:sdk-bugcollect:VERSION")
implementation("com.xuqm:sdk-core:VERSION") // 必须
Release 构建先应用 com.xuqm.common，开启 R8 mapping 上传时再应用
com.xuqm.bugcollect。配置验证与 buildId 只由 common 插件负责，BugCollect 插件
不会维护第二套配置路径或初始化定义。Debug 固定关闭自动采集与上传；隐藏开发测试
入口仅允许在可调试、非应急禁用、隐私已同意且平台已开通时显式发送一次，不改变自动状态。
快速开始
// 宿主取得隐私同意后同步一次；撤回时传 false。
XuqmSDK.setPrivacyConsent(true)
BugCollect.setLogLevel(LogLevel.INFO)
BugCollect.setEnvironment("production")
// 业务代码中
BugCollect.event("page_view", mapOf("page" to "home"))
BugCollect.captureError(exception)
API
BugCollect 对象
| API | 说明 |
|---|---|
BugCollect.setLogLevel(level) |
设置日志级别（DEBUG / INFO / WARN / ERROR） |
BugCollect.setEnvironment(env) |
设置环境标签 |
BugCollect.addBreadcrumb(category, message, level?, data?) |
添加最近操作线索，最多保留 50 条 |
BugCollect.event(name, properties?) |
记录自定义事件 |
BugCollect.captureError(error, tags?, fingerprint?) |
上报异常；可选传入业务标签或自定义聚合指纹 |
BugCollect.warn(message, tags?) |
记录警告 |
BugCollect.info(message, tags?) |
记录信息 |
BugCollect.defineFunnel(id, steps) |
定义漏斗 |
LogLevel
enum class LogLevel { DEBUG, INFO, WARN, ERROR, NONE }
工作原理
- 运行门禁：仅在平台启用且宿主已同意隐私时注册采集器
- LogQueue：error/fatal 加密持久化，普通事件仅驻留内存；最多 500 条、保留 7 天
- CrashCapture：捕获未处理 Java/Kotlin 异常，加密保存后在下次启动上传
- Fingerprint：基于异常类型、归一化 message 和首个业务堆栈生成指纹，服务端去重聚合
- FunnelTracker：客户端维护漏斗进度，服务端跨 session 聚合
配置
bugCollectApiUrl 和 bugCollectEnabled 由 sdk-core 在 init 后从平台配置自动获取，无需 App 传入。
后台上传失败采用带随机抖动的指数退避，最多尝试 3 次，不会向宿主主线程抛错。
服务端返回固定业务码 BUGCOLLECT_DISABLED 时立即停止采集、清除队列，直到平台配置明确重新启用。
Release 的 R8 mapping 上传由 Gradle 插件从 XUQM_API_TOKEN Gradle 属性或同名环境变量
取得 Bearer 令牌。令牌不得写入 config.xuqmconfig、源码或日志。平台启用 BugCollect
但构建机未提供令牌时 Release 失败；-Pxuqm.bugcollect=disabled 应急构建不上传且不要求令牌。
