🔍 Lorine

一个轻量级、框架无关的纯 TypeScript 前端用户行为追踪日志框架。

✨ 特性

- 🎯 全面追踪 - 自动捕获页面路由、点击、表单、API、错误和自定义事件
- 🔌 插件化架构 - 灵活的追踪器插件系统,支持按需启用
- 💾 本地存储 - 基于 IndexedDB 的高性能本地持久化
- 📤 批量上报 - 智能批量上传机制,支持自动重试
- 📊 日志导出 - 支持 JSON/CSV 格式导出,便于数据分析
- 🛡️ 隐私保护 - 自动过滤敏感信息(密码、token 等)
- ⚡ 性能优化 - 内置节流防抖,避免影响主业务性能
- 🔒 类型安全 - 完整的 TypeScript 类型定义

📦 安装

``bash
npm install lorine
`

🚀 快速开始

$3

`typescript
import { init } from 'lorine';

// 初始化追踪器
const tracer = await init({
userId: 'user_123',
uploadUrl: 'https://api.example.com/logs',
trackers: {
route: { enabled: true },
click: { enabled: true },
form: { enabled: true },
api: { enabled: true },
error: { enabled: true }
}
});

// 之后所有用户行为将自动追踪
`

$3

`typescript
// 追踪自定义业务事件
tracer.trackCustom('purchase_completed', {
orderId: 'order_789',
amount: 6999,
paymentMethod: 'wechat'
});
`

📖 详细配置

$3

`typescript
interface TracerConfig {
// 用户标识
userId?: string;

// 上报配置
uploadUrl?: string;
uploadInterval?: number; // 上报间隔 (毫秒)
maxBatchSize?: number; // 批量大小

// 追踪器配置
trackers?: {
route?: RouteTrackerConfig;
click?: ClickTrackerConfig;
form?: FormTrackerConfig;
api?: APITrackerConfig;
error?: ErrorTrackerConfig;
custom?: CustomTrackerConfig;
};

// 敏感字段过滤
sensitiveFields?: string[]; // 默认: ['password', 'token']

// 调试模式
debug?: boolean;
}
`

$3

`typescript
tracer.init({
trackers: {
click: {
enabled: true,
// 只追踪特定元素
includeSelectors: ['button', 'a', '[data-track]'],
// 排除某些元素
excludeSelectors: ['.no-track'],
// 节流时间 (毫秒)
throttle: 300,
// 是否捕获文本内容
captureText: true,
// 是否捕获点击位置
capturePosition: true
}
}
});
`

$3

`typescript
tracer.init({
trackers: {
form: {
enabled: true,
// 排除敏感表单
excludeSelectors: ['#login-form', '.sensitive'],
// 是否捕获字段内容
captureFields: true
}
}
});
`

$3

`typescript
tracer.init({
trackers: {
api: {
enabled: true,
// 排除某些 URL
excludeUrls: ['/internal-api'],
// 是否捕获请求体
captureRequestBody: true,
// 是否捕获响应体
captureResponseBody: true
}
}
});
`

📝 日志数据结构

每条日志事件包含以下信息:

`typescript
interface LogEvent {
id: string; // 事件唯一ID
type: EventType; // 事件类型 (route/click/form/api/error/custom)
timestamp: number; // 时间戳
sequence: number; // 序列号
sessionId: string; // 会话ID
userId?: string; // 用户ID
deviceId: string; // 设备指纹
payload: any; // 事件数据
metadata: { // 元数据
url: string;
userAgent: string;
viewport: { width: number; height: number };
};
}
`

🔧 API 方法

$3

`typescript
// 查询日志
const logs = await tracer.queryLogs({
sessionId: 'session_xyz',
type: 'click',
startTime: Date.now() - 3600000,
limit: 100
});

// 导出日志
await tracer.exportLogs('json', 'logs.json');
await tracer.exportLogs('csv', 'logs.csv');

// 清空日志
await tracer.clearLogs();

// 获取日志数量
const count = await tracer.getLogCount();

// 清理过期日志 (7天前)
const deleted = await tracer.cleanupOldLogs(7 24 60 60 1000);
`

$3

`typescript
// 获取会话信息
const sessionId = tracer.getSessionId();
const deviceId = tracer.getDeviceId();

// 设置用户ID
tracer.setUserId('user_456');
`

$3

`typescript
// 启动/停止特定追踪器
tracer.startTracker('click');
tracer.stopTracker('click');

// 启动/停止所有追踪器
tracer.startAllTrackers();
tracer.stopAllTrackers();
`

🌟 使用场景

$3

`typescript
// 自动追踪所有点击和页面访问
const tracer = await init({
trackers: {
route: { enabled: true },
click: { enabled: true }
}
});

// 分析用户点击热力图
const clickLogs = await tracer.queryLogs({ type: 'click' });
`

$3

`typescript
// 自动捕获所有 JS 错误
const tracer = await init({
trackers: {
error: { enabled: true, captureStackTrace: true }
}
});

// 查询错误日志
const errors = await tracer.queryLogs({ type: 'error' });
`

$3

`typescript
// 追踪所有 API 请求
const tracer = await init({
trackers: {
api: { enabled: true }
}
});

// 分析慢请求
const apiLogs = await tracer.queryLogs({ type: 'api' });
const slowRequests = apiLogs.filter(log => log.payload.duration > 3000);
`

$3

`typescript
// 关键步骤埋点
tracer.trackCustom('view_product', { productId: '001' });
tracer.trackCustom('add_to_cart', { productId: '001' });
tracer.trackCustom('checkout_start', { amount: 6999 });
tracer.trackCustom('payment_success', { orderId: '789' });

// 查询转化路径
const funnel = await tracer.queryLogs({
type: 'custom',
sessionId: currentSessionId
});
`

🎨 声明式埋点

在 HTML 中使用 data-track-* 属性:

`html
data-track="purchase"
data-track-category="商品"
data-product-id="001"
data-price="6999">
立即购买

`

点击时自动记录所有 data-* 属性。

📊 数据导出示例

$3

`json
{
"exportTime": 1737878500000,
"version": "1.0",
"count": 150,
"events": [
{
"id": "evt_abc123",
"type": "click",
"timestamp": 1737878400000,
"sessionId": "session_xyz",
"payload": { ... }
}
]
}
`

$3

`csv
id,type,timestamp,sequence,sessionId,userId,url,payloadSummary
evt_abc123,click,1737878400000,1,session_xyz,user_456,/products,点击: 加入购物车按钮
`

🔒 隐私保护

框架自动过滤敏感信息:

- 密码字段自动标记为 [FILTERED]
- 手机号自动脱敏: 138**8888
- 邮箱自动脱敏: us**@example.com
- 支持自定义敏感字段列表

`typescript
tracer.init({
sensitiveFields: ['password', 'token', 'ssn', 'creditCard']
});
`

🛠️ 开发

`bash


安装依赖

npm install

开发模式

npm run dev

构建

npm run build

测试

npm test
``

📄 License

MIT

🤝 贡献

欢迎提交 Issue 和 Pull Request!