# KTrace SDK
一个轻量级、跨平台的埋点分析SDK，支持多种前端框架和原生HTML项目。
## 特性
- 🚀 **轻量级**: 压缩后体积小，性能优异
- 🔧 **易集成**: 简单的API设计，快速集成到项目中
- 🌐 **跨平台**: 支持HTML、React、Vue等多种前端环境
- 📊 **丰富事件**: 支持页面访问、用户交互、错误监控等多种事件类型
- 🛡️ **类型安全**: 完整的TypeScript类型定义
- 🔍 **调试友好**: 内置调试模式，便于开发调试
- ⚡ **自动追踪**: 支持自动追踪页面访问、错误等常见事件
## 安装
### NPM 安装
```bash
npm install @ked3/ktrace
```
### CDN 引入
```html
```
## 快速开始
### HTML 原生项目
```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
- 查看项目文档