tracker

Tracker SDK 是一款面向现代 Web 应用的轻量级分析库，尤其适合 AI 辅助工具（如 Vibe Coding）生成的项目。其核心设计理念是简洁：只需一次 `init` 调用即可配置收集端点，页面浏览会自动记录，自定义事件可通过 `track(eventName, data)` 发送。 **核心功能** - **零配置启动**——添加一个 script 标签或 npm 导入即可开始收集数据。 - **自动页面浏览检测**——SDK 监听导航事件，无需额外代码即可发送 `pageview` 载荷。 - **自定义事件追踪**——开发者可通过调用 `track` 记录任意交互行为。 - **设备指纹识别**——基于 Canvas 的指纹技术可唯一标识访问者，同时尊重隐私。 - **离线队列**——发送失败的事件会存储在本地存储中并在后续重试，最大限度地减少数据丢失。 - **会话管理**——会话自动创建，并在可配置的超时时间（默认 30 分钟）后过期。 - **可配置批量发送**——事件分组为单个请求以减小网络开销。 **安装方式** - **CDN**——在 HTML 中直接引入 UMD 包并调用 `WFTK.init({ endpoint: 'https://your-api.com/api/v1/collect/event', debug: true })`。 - **npm**——执行 `npm install @weavefox/tracker`，然后导入函数：`import { init, track, setUserId } from '@weavefox/tracker';`。 **公开 API** | 方法 | 用途 | |--------|---------| | `init(config)` | 使用端点、appId 和可选标志初始化 SDK。 | | `track(eventName, data)` | 发送自定义事件。 | | `trackPageview(data)` | 手动记录页面浏览（默认自动启用）。 | | `setUserId(userId)` | 将已登录用户与后续事件关联。 | | `getFingerprint()` | 获取生成的设备指纹。 | | `flush()` | 立即发送队列中的所有事件。 | **配置选项** ```javascript WFTK.init({ endpoint: 'required', // 收集服务 URL appId: 'optional', // 应用标识符 autoPageview: true, // 自动追踪页面浏览 debug: false, // 启用控制台调试 enableQueue: true, // 网络故障时离线存储事件 sessionTimeout: 1800000, // 会话空闲超时（毫秒），默认 30 分钟 maxEventsPerSession: 1000 // 每个会话的事件上限 }); ``` **载荷格式**——每次请求包含一个 JSON 主体，含可选的 `appId` 和 `events` 数组。每个事件包含必填的 `event` 名称、`timestamp`（时间戳）、`nonce`（用于去重）、`fingerprint`（指纹），以及包含系统收集上下文（URL、标题、设备信息等）的 `data` 对象。用户定义字段放入 `biz` 子对象中，实现分析数据与业务数据的分离。 **服务端注意事项** - **时间戳校验**——拒绝超过 5 分钟的老事件，防止重放攻击。 - **Nonce 去重**——使用 Redis 等存储 nonce，设置 24 小时 TTL，确保幂等性。 - **速率限制**——按 IP 和指纹分别应用限制，遏制滥用行为。 - **应用识别**——优先使用载荷中的显式 `appId`；如需回退，可使用请求的 `Referer` 主机名。 - **示例 Express 处理器**——README 中提供了简洁的 Node.js 代码片段，用于验证时间戳、检查 nonce 并持久化事件。 **许可证**——采用 MIT 许可证分发，允许在开源和商业项目中不受限制地使用。 总体而言，Tracker SDK 为需要可靠客户端侧分析功能的开发者提供了一种简单、注重隐私的解决方案，避免了重量级平台带来的负担。