npm package: @ked3/ktrace
Description: 跨平台埋点分析SDK
Latest version: 1.2.4

# 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
- 查看项目文档