Package Exports
- @tp5er/web-trace-sdk
- @tp5er/web-trace-sdk/global
Readme
@tp5er/web-trace-sdk
高性能跨端事件追踪与 RUM（真实用户监控）SDK，支持自动埋点、错误监控与离线重试。
特性
- 跨端支持: 同时支持浏览器和 Node.js 环境
- 自动埋点: 自动收集用户行为、页面浏览、性能指标、网络请求等数据
- 插件系统: 灵活的插件架构，支持依赖管理和优先级控制
- 智能队列: 支持事件去重、优先级队列、批量发送、动态调整
- 离线缓存: 支持离线事件缓存，网络恢复后自动重试
- 错误监控: 完善的错误处理和统计系统
- 设备识别: 基于浏览器指纹的稳定设备ID生成
- 会话管理: 自动会话创建、维护和超时处理
- TypeScript: 完整的类型定义，提供优秀的开发体验
安装
npm install @tp5er/web-trace-sdk
# 或
pnpm add @tp5er/web-trace-sdk
# 或
yarn add @tp5er/web-trace-sdk快速开始
基础使用
import { init, track, use, plugins } from 'web-trace-sdk'
// 初始化 SDK
init({
appId: 'your-app-id',
appKey: 'your-app-key',
endpoint: 'https://your-analytics-api.com/collect',
debug: true,
sampleRate: 1,
batchSize: 20,
batchInterval: 1000,
offlineEnabled: true,
maxQueueSize: 1000,
retryCount: 3,
retryInterval: 1000,
})
// 注册内置插件
use(plugins.user)
use(plugins.browser)
use(plugins.session)
use(plugins.behavior)
use(plugins.performance)
use(plugins.pageview)
use(plugins.network)
use(plugins.error)
// 追踪自定义事件
track('button_click', {
button_name: 'submit',
page: '/checkout',
category: 'user_action'
})浏览器环境使用
<script src="https://cdn.jsdelivr.net/npm/@tp5er/web-trace-sdk/dist/index.global.js"></script>
<script>
NodeTrace.init({
appId: 'your-app-id',
endpoint: 'https://your-analytics-api.com/collect'
})
NodeTrace.use(NodeTrace.plugins.user)
NodeTrace.use(NodeTrace.plugins.browser)
NodeTrace.track('page_view', {
title: document.title
})
</script>API 文档
初始化
init(options: Options): void配置选项：
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| appId | string | - | 应用 ID（必填） |
| appKey | string | '' | 应用密钥 |
| endpoint | string | - | 数据上报接口地址（必填） |
| debug | boolean | false | 是否开启调试模式 |
| sampleRate | number | 1 | 采样率（0-1） |
| blacklist | string[] | [] | 事件黑名单 |
| whitelist | string[] | - | 事件白名单 |
| batchSize | number | 20 | 批量发送大小 |
| batchInterval | number | 1000 | 批量发送间隔（毫秒） |
| offlineEnabled | boolean | false | 是否启用离线缓存 |
| maxQueueSize | number | 1000 | 最大队列大小 |
| retryCount | number | 3 | 重试次数 |
| retryInterval | number | 1000 | 重试间隔（毫秒） |
| headers | Record<string, string> | {} | 请求头 |
| timeout | number | 30000 | 请求超时时间（毫秒） |
| beforeSend | function | - | 发送前回调 |
事件追踪
track<T extends EventProperties>(event: string, properties?: T): void追踪自定义事件：
track('purchase', {
product_id: '12345',
price: 99.99,
currency: 'USD'
})插件管理
use(plugin: IPlugin): void注册插件：
use(plugins.user)
use(plugins.browser)用户管理
// 获取设备 ID
getDeviceId(): string
// 设置用户 ID
setID(id: string): void
// 获取用户 ID
getID(): string
// 清除用户 ID
clearID(): void
// 异步生成稳定的设备 ID
generateStableDeviceIdAsync(): Promise<string>浏览器数据
// 获取浏览器数据
getBrowserData(): BrowserData
// 浏览器工具方法
browserUtils.getBrowser()
browserUtils.getDeviceType()
browserUtils.getNetworkState()队列管理
// 手动刷新队列
flush(): Promise<void>
// 清除所有定时器
clearTimers(): void会话管理
// 获取会话管理器
sessions.getID(): string
sessions.getStartTime(): number
sessions.getDuration(): number
sessions.isNew(): boolean
sessions.getStats(): { pageViews: number; events: number; duration: number }行为追踪
// 获取行为管理器
behaviors.getPath(): BehaviorStep[]
behaviors.getRecent(limit?: number): BehaviorStep[]
behaviors.getStats(): { totalSteps: number; uniqueEvents: number; averageTimeBetweenSteps: number }
behaviors.getContext(): EventProperties
behaviors.analyze(): { mostFrequentEvents: Array<{ event: string; count: number }>; commonPaths: Array<{ path: string; count: number }>; averageSessionDuration: number }内置插件
User Plugin
用户管理插件，负责设备 ID 和用户 ID 的生成、存储和管理。
use(plugins.user)功能:
- 基于浏览器指纹生成稳定的设备 ID
- 用户 ID 的设置和获取
- 自动为所有事件添加设备 ID 和用户 ID
Browser Plugin
浏览器数据收集插件，自动收集浏览器环境信息。
use(plugins.browser)功能:
- 设备信息（屏幕分辨率、像素比等）
- 浏览器信息（类型、版本、引擎等）
- 网络信息（连接类型、速度等）
- 页面信息（URL、标题、引用来源等）
- 自动为所有事件添加浏览器数据
Session Plugin
会话管理插件，负责会话创建、维护和超时处理。
use(plugins.session)功能:
- 自动创建和维护会话
- 30 分钟无活动自动超时
- 记录会话统计数据（页面浏览数、事件数、持续时间）
- 自动为所有事件添加会话信息
Behavior Plugin
行为追踪插件，负责追踪用户行为和页面浏览。
use(plugins.behavior)功能:
- 记录用户行为路径
- 行为统计分析
- 最近行为追踪
- 自动为所有事件添加行为上下文
Performance Plugin
性能监控插件，负责收集页面性能数据。
use(plugins.performance)功能:
- 页面加载时间
- 首字节时间（TTFB）
- DOM 解析时间
- 首次绘制时间（FP）
- 首次内容绘制时间（FCP）
- 资源加载统计
Pageview Plugin
页面浏览插件，负责监控和追踪页面浏览事件。
use(plugins.pageview)功能:
- 自动追踪页面浏览事件
- 监听路由变化（hashchange、popstate、pushState、replaceState）
- 依赖 session 和 behavior 插件
Network Plugin
网络监控插件，负责监控和追踪网络请求。
use(plugins.network)功能:
- 自动监控 XMLHttpRequest 请求
- 自动监控 fetch 请求
- 记录请求方法、URL、状态、耗时等
- 自动排除 SDK 自己的上报请求
Error Plugin
错误监控插件，负责捕获和处理错误。
use(plugins.error)功能:
- 捕获 JavaScript 错误
- 捕获 Promise 错误
- 捕获资源加载错误
- 完善的错误分类和统计
自定义插件
import { use } from '@tp5er/web-trace-sdk'
import type { IPlugin, IPluginContext, Payload, EventProperties } from '@tp5er/web-trace-sdk'
const customPlugin: IPlugin = {
name: 'custom',
version: '1.0.0',
description: '自定义插件',
priority: 10,
dependencies: ['user'],
setup(context: IPluginContext) {
console.log('插件初始化')
},
onTrack<T extends EventProperties>(payload: Payload<T>): Payload<T> {
console.log('事件追踪前', payload)
return payload
},
onTracked<T extends EventProperties>(payload: Payload<T>): void {
console.log('事件追踪后', payload)
},
beforeSend<T extends EventProperties>(events: Payload<T>[]): Payload<T>[] {
console.log('发送前', events.length)
return events
},
afterSend<T extends EventProperties>(events: Payload<T>[], success: boolean): void {
console.log('发送后', success)
}
}
use(customPlugin)高级特性
智能队列管理
- 事件去重: 自动过滤重复事件
- 优先级队列: 根据事件类型设置优先级
- 动态调整: 根据队列压力动态调整批量大小和发送间隔
- 离线缓存: 网络断开时自动缓存事件
- 自动重试: 发送失败时自动重试，支持指数退避
插件生命周期
插件支持完整的生命周期钩子：
beforeInit: 初始化前setup: 设置init: 初始化activate: 激活afterInit: 初始化后onTrack: 事件追踪前onTracked: 事件追踪后beforeSend: 发送前afterSend: 发送后deactivate: 停用destroy: 销毁beforeDestroy: 销毁前afterDestroy: 销毁后
错误处理
SDK 提供完善的错误处理机制：
import {
captureError,
handleNetworkError,
handleStorageError,
handleBrowserError,
handlePluginError
} from '@tp5er/web-trace-sdk'
// 捕获错误
captureError('network', '请求失败', error, { url: 'xxx' }, 'error')
// 处理特定类型错误
handleNetworkError(error, { context: 'upload' })
handleStorageError(error, { key: 'user_id' })
handleBrowserError(error, { context: 'fingerprint' })
handlePluginError(error, { plugin: 'custom' })License
作者
zhiqiang