ctc-track-plugin/README.md

uniapp 小程序埋点劫持

# CTC Track Plugin

## 简介
CTC Track Plugin 是一个专为 uniapp 小程序设计的埋点劫持插件，用于自动收集和发送用户行为数据，如页面访问、点击事件等。通过劫持用户行为，插件能够无缝集成到项目中，无需手动添加埋点代码，大幅提升开发效率。

### 项目背景
随着小程序生态的快速发展，用户行为数据的采集和分析变得越来越重要。传统的埋点方式需要开发者在代码中手动添加埋点逻辑，不仅繁琐，还容易遗漏。CTC Track Plugin 旨在解决这一问题，通过自动化埋点技术，帮助开发者快速集成埋点功能，提升数据采集的准确性和效率。


## 核心功能
- **自动页面埋点**：记录用户访问的页面路径和停留时间，无需手动配置。
- **点击事件劫持**：自动拦截用户点击事件，并发送埋点数据。
- **批量处理**：支持定时或按批次大小自动发送埋点数据，减少网络请求频率。
- **Vue 插件集成**：提供 Vue 插件，方便在 uniapp 项目中快速集成。
- **自定义事件**：支持手动触发埋点事件，并传递自定义参数，满足个性化需求。


## 使用指南
### 1. 配置 Vite 插件
在 `vite.config.js` 中引入插件，并确保插件顺序正确：
```typescript
import InjectClickHandler from 'ctc-track-plugin/inject';

plugins: [
   InjectClickHandler(), // 必须写在 uniPlugin 前面
   Uni,
   // ...
]
```

### 2. 集成到 Vue 应用
在 `main.ts` 中初始化插件，并配置基础参数：
```typescript
import TrackAutomaticPlugin from 'ctc-track-plugin';
import pagesJson from '@/pages.json'

export function createApp() {
   const app = createSSRApp(App);
   app.use(TrackAutomaticPlugin, {
      app_entity_source: 402,
      channel_source: 201,
   },pagesJson);
   // ...
}
```

### 3. 配置埋点
- 在 `pages.config.ts` 中配置页面标题和路径。
- 插件会自动劫持点击事件和页面跳转事件，无需额外代码。

## 使用场景
### 场景一：页面访问统计
插件会自动记录用户访问的页面路径和停留时间，适用于分析用户行为路径和页面热度。

### 场景二：按钮点击分析
通过劫持点击事件，插件可以统计用户点击频率最高的按钮，帮助优化交互设计。

### 场景三：自定义事件采集
开发者可以通过手动触发埋点事件，采集特定业务场景的数据，如订单提交、用户注册等。

## 构建与发布
运行以下命令构建插件：
```bash
pnpm build
```

## 注意事项
1. **依赖要求**：确保项目已安装 `vue`依赖。
2. **模块格式**：插件默认使用 `ES` 模块格式，如需其他格式，请修改 `tsup.config.ts`。
3. **兼容性**：插件仅支持 uniapp 小程序环境。
4. **性能优化**：建议在非生产环境下关闭埋点功能，以减少性能开销。

## 常见问题（FAQ）
### Q1: 插件是否支持 H5 环境？
A: 目前插件仅支持 uniapp 小程序环境，H5 环境的支持正在开发中。

### Q2: 如何调试埋点数据？
A: 可以在开发环境下开启调试模式，插件会将埋点数据打印到控制台。

### Q3: 数据发送失败如何处理？
A: 插件内置了重试机制，如果数据发送失败，会自动尝试重新发送。

## 贡献指南
欢迎开发者通过以下方式为项目贡献力量：
1. 提交 Issue 报告问题或提出建议。
2. 提交 Pull Request 改进代码或文档。
3. 分享使用经验或教程。

## 联系方式
如有任何问题或建议，请联系：
- 邮箱：1776787598@qq.com

## 许可证
ISC