@ked3/ktrace

# KTrace SDK 一个轻量级、跨平台的埋点分析SDK，支持多种前端框架和原生HTML项目。 ## 特性 - 🚀 **轻量级**: 压缩后体积小，性能优异 - 🔧 **易集成**: 简单的API设计，快速集成到项目中 - 🌐 **跨平台**: 支持HTML、React、Vue等多种前端环境 - 📊 **丰富事件**: 支持页面访问、用户交互、错误监控等多种事件类型 - 🛡️ **类型安全**: 完整的TypeScript类型定义 - 🔍 **调试友好**: 内置调试模式，便于开发调试 - ⚡ **自动追踪**: 支持自动追踪页面访问、错误等常见事件 ## 安装 ### NPM 安装 ```bash npm install @ked3/ktrace ``` ### CDN 引入 ```html <script src="https://unpkg.com/@ked3/ktrace@latest/dist/ktrace.min.js"></script> ``` ## 快速开始 ### HTML 原生项目 ```html <!DOCTYPE html> <html> <head> <script src="./ktrace.min.js"></script> </head> <body> <script> // 初始化追踪器 const tracker = new KTrace.HtmlAdapter({ project_id: "your_project_id", enable_auto_track: true, debug: true }); // 启动追踪 tracker.init(); // 手动追踪事件 tracker.trackEvent(KTrace.EventKey.BUTTON_CLICK, { button_type: 'submit', page_section: 'header' }); </script> </body> </html> ``` ### ES6 模块 ```javascript import { HtmlAdapter, EventKey } from '@ked3/ktrace'; // 初始化追踪器 const tracker = new HtmlAdapter({ project_id: "your_project_id", server_url: "https://your-analytics-server.com", enable_auto_track: true, debug: false }); // 启动追踪 tracker.init(); // 追踪自定义事件 tracker.trackEvent(EventKey.USER_LOGIN, { user_id: '12345', login_method: 'email' }); ``` ## 配置选项 ```typescript interface TrackerConfig { /** 项目ID，必填项 */ project_id: string; /** 数据上报的服务器地址（可选） */ server_url?: string; /** 单条事件上报路径（可选） */ event_path?: string; /** 批量事件上报路径（可选） */ batch_event_path?: string; /** 是否启用自动埋点功能 */ enable_auto_track?: boolean; /** 是否开启调试模式 */ debug?: boolean; } ``` ## 支持的事件类型 ### 页面相关事件 - `PAGE_VIEW` - 页面访问 - `PAGE_LEAVE` - 页面离开 - `PAGE_VISIBILITY_CHANGE` - 页面可见性变化 - `ROUTE_CHANGE` - 路由变化 ### 用户交互事件 - `BUTTON_CLICK` - 按钮点击 - `USER_INPUT` - 用户输入 - `SCROLL` - 滚动 - `HOVER` - 鼠标悬停 - `DOUBLE_CLICK` - 双击 - `RIGHT_CLICK` - 右键点击 - `DRAG` / `DROP` - 拖拽操作 - `FOCUS` / `BLUR` - 焦点变化 - `CUSTOM_INTERACTION` - 自定义交互 - `FEEDBACK_SUBMIT` - 反馈提交 ### 错误监控事件 - `JAVASCRIPT_ERROR` - JavaScript错误 - `RESOURCE_ERROR` - 资源加载错误 - `NETWORK_ERROR` - 网络错误 - `COMPONENT_ERROR` - 组件错误 - `CUSTOM_ERROR` - 自定义错误 ### 业务事件 - `USER_LOGIN` - 用户登录 - `USER_LOGOUT` - 用户登出 - `COMPONENT_LIFECYCLE` - 组件生命周期 ## API 参考 ### HtmlAdapter #### 构造函数 ```javascript const tracker = new HtmlAdapter(config); ``` #### 方法 ##### `init()` 初始化追踪器，设置自动追踪和错误监听。 ```javascript tracker.init(); ``` ##### `trackEvent(eventKey, metadata?)` 追踪自定义事件。 ```javascript tracker.trackEvent(EventKey.BUTTON_CLICK, { button_id: 'submit-btn', page_section: 'form' }); ``` ##### `trackError(error, eventKey?, metadata?)` 追踪错误事件。 ```javascript try { // 可能出错的代码 } catch (error) { tracker.trackError(error, EventKey.JAVASCRIPT_ERROR, { context: 'user_action' }); } ``` ##### `trackPageView(path?)` 手动追踪页面访问。 ```javascript tracker.trackPageView('/custom-page'); ``` ## 自动追踪功能当 `enable_auto_track` 设置为 `true` 时，SDK会自动追踪以下事件： - 页面加载完成时的页面访问事件 - 页面离开事件 - JavaScript运行时错误 - 资源加载错误 - Promise未捕获的错误 ## 调试模式开启调试模式后，SDK会在控制台输出详细的日志信息： ```javascript const tracker = new HtmlAdapter({ project_id: "your_project_id", debug: true // 开启调试模式 }); ``` ## 示例项目查看 `docs/examples/` 目录下的示例文件： - `demo.html` - 基础功能演示 - `demo2.html` - 高级功能演示 ## 开发 ### 安装依赖 ```bash pnpm install ``` ### 构建项目 ```bash pnpm run build ``` ### 运行测试 ```bash pnpm run test ``` ### 启动开发服务器 ```bash pnpm run dev ``` ## 版本历史 ### v1.2.2 - 优化错误处理机制 - 增加更多事件类型支持 - 改进TypeScript类型定义 ## 许可证 MIT License ## 贡献欢迎提交 Issue 和 Pull Request 来帮助改进这个项目。 ## 支持如果您在使用过程中遇到问题，请通过以下方式获取帮助： - 查看示例代码 - 提交 GitHub Issue - 查看项目文档