XuqmGroup-RNSDK/packages/log/README.md

@xuqm/rn-log

XuqmGroup RN SDK 日志模块。提供日志采集、错误追踪、漏斗分析能力。

安装

yarn add @xuqm/rn-log

Peer dependencies：@xuqm/rn-common >= 0.4.0，@react-native-async-storage/async-storage >= 1.21.0，react-native >= 0.76

快速开始

import { XLog } from '@xuqm/rn-log'

// 1. 设置日志级别
XLog.setLogLevel('debug')  // 'debug' | 'info' | 'warn' | 'error'

// 2. 设置环境标签
XLog.setEnvironment('production')  // 'development' | 'staging' | 'production'

// 3. 开启全局错误捕获（App 启动时调用一次）
XLog.startCapture()

// 4. 记录自定义事件
XLog.event('page_view', { page: 'home' })

// 5. 上报错误
try { ... } catch (e) { XLog.captureError(e) }

API

XLog 对象

API	说明
XLog.setLogLevel(level)	设置最低日志级别（低于此级别的事件被丢弃）
XLog.setEnvironment(env)	设置环境标签（附加到每个事件）
XLog.startCapture()	开启全局 JS 错误和未处理 Promise rejection 捕获
XLog.event(name, properties?)	记录自定义分析事件
XLog.captureError(error, metadata?)	上报 JS 异常
XLog.warn(message, metadata?)	记录警告（需级别允许）
XLog.info(message, metadata?)	记录信息事件（需级别允许）
XLog.defineFunnel(id, steps)	定义漏斗（按步骤顺序追踪转化）
XLog.getFunnelProgress(funnelId)	获取客户端漏斗进度
XLog.flush()	立即刷新所有待发送事件（如 App 进后台前调用）

事件类型

类型	说明
LogEvent	自定义事件（type: 'event'）
IssueEvent	错误事件（type: 'js_error' / 'native_crash' / 'api_error' / 'warning'）

日志级别

'debug' (0) < 'info' (1) < 'warn' (2) < 'error' (3)

漏斗分析示例

import { XLog } from '@xuqm/rn-log'

// 定义漏斗
XLog.defineFunnel('checkout', ['cart_view', 'checkout_start', 'payment_done'])

// 在业务代码中记录步骤事件（SDK 自动推进漏斗）
XLog.event('cart_view')
XLog.event('checkout_start')
XLog.event('payment_done')

// 查询进度
const progress = XLog.getFunnelProgress('checkout')
console.log(progress?.completedSteps) // ['cart_view', 'checkout_start', 'payment_done']

工作原理

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

配置

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