lorine

🔍 Lorine

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

✨ 特性

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

📦 安装

npm install lorine

🚀 快速开始

基础用法

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 }
  }
});

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

手动埋点

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

📖 详细配置

初始化配置

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;
}

点击追踪配置

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

表单追踪配置

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

API 追踪配置

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

📝 日志数据结构

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

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 方法

日志管理

// 查询日志
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);

会话管理

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

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

追踪器控制

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

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

🌟 使用场景

1. 用户行为分析

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

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

2. 错误监控

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

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

3. API 性能监控

// 追踪所有 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);

4. 转化漏斗分析

// 关键步骤埋点
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-* 属性:

<button 
  data-track="purchase"
  data-track-category="商品"
  data-product-id="001"
  data-price="6999">
  立即购买
</button>

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

📊 数据导出示例

JSON 格式

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

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
• 支持自定义敏感字段列表

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

🛠️ 开发

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

# 测试
npm test

📄 License

MIT

🤝 贡献

欢迎提交 Issue 和 Pull Request!