npm package: @rl521/track-sdk
Description: Vue 埋点工具包，兼容 Vue2/Vue3，支持自动埋点、自定义配置等
Author: wwb
Latest version: 1.0.0


# @rl521/track-sdk

Vue 埋点工具包，兼容 Vue2/Vue3，支持全局自动埋点、自定义配置、用户信息关联等功能，可直接上传 npm 使用。

## 特性
- ✅ 兼容 Vue2 / Vue3（自动识别版本，适配 ESM/CJS 模块）
- ✅ 支持全局挂载，自动埋点（页面访问、按钮点击）
- ✅ 自定义配置（上报地址、调试模式、公共参数等）
- ✅ 支持登录后重新加载路由信息
- ✅ 可设置访问者、租户、部门信息并关联埋点数据
- ✅ 支持自定义埋点上报
- ✅ TypeScript 开发，完整类型提示
- ✅ 修复 Vue3 ESM 无默认导出、模块导出、npm link 使用及 Vue 实例时序报错问题
- ✅ 修复 `install is not defined` 导出报错，兼容多模块导入场景

## 埋点指标

### 1. PV（Page View，页面浏览量）
- 定义：用户每次打开或刷新一个页面，都会被记录为一次 PV。
- 特点：
  - 同一用户多次访问同一页面会被累加。
  - 反映的是页面的总访问次数。
- 用途： 
  - 衡量网站或应用的流量规模。
  - 分析热门页面的受欢迎程度。

### 2. UV（Unique Visitor，独立访客数）
- 定义：在一定时间范围内（如一天、一周），访问网站或应用的不同用户数量。
- 特点：
    - 通过用户的唯一标识（如 Cookie、IP 地址、设备 ID 等）去重。 
    - 同一用户多次访问只计算一次。
- 用途：
    - 衡量真实的用户规模。 
    - 评估用户粘性和覆盖面。
  
### 3. PD（Page Duration，页面停留时长）
- 定义：用户访问页面时，页面停留的时间。
- 特点：
  - 通常以秒为单位计算。
  - 可以反映用户对内容的兴趣程度。
- 用途：
  - 分析用户对页面内容的关注度。
  - 优化页面设计和内容布局。

## 安装

### npm
```bash
npm install @rl521/track-sdk --save
```

### yarn
```bash
yarn add @rl521/track-sdk
```

## 使用方法

### 1. 全局引入并初始化（Vue3）
#### 方式一：命名导入（推荐，适配 ESM 规范，避免导出报错）
```typescript
// main.ts
import { createApp } from 'vue';
import App from './App.vue';
import router from './router';
// 直接导入 install 方法，避免解构歧义
import { trackerInstall } from '@rl521/track-sdk';

const app = createApp(App);

// 安装并初始化埋点 SDK（使用直接导入的 trackerInstall 方法）
app.use(trackerInstall, {
    reportUrl: 'https://your-report-url.com/api/track', // 必填：上报地址
    debug: process.env.NODE_ENV === 'development', // 开发环境开启调试
    autoTrack: true, // 开启自动埋点
    extraParams: { appId: 'your-app-id' }, // 公共参数
    reportDelay: 0 // 上报延迟（ms）
});

app.use(router).mount('#app');
```

#### 方式二：默认导入（兼容旧代码，已修复导出问题）
```typescript
// main.ts
import { createApp } from 'vue';
import App from './App.vue';
import router from './router';
import TrackSdk from '@rl521/track-sdk';

const app = createApp(App);

// 安装并初始化埋点 SDK（从默认导出中使用 trackerInstall）
app.use(TrackSdk.trackerInstall, {
    reportUrl: 'https://your-report-url.com/api/track',
    debug: process.env.NODE_ENV === 'development',
    autoTrack: true
});

app.use(router).mount('#app');
```

### 2. 全局引入并初始化（Vue2）
#### 方式一：命名导入（推荐）
```javascript
// main.js
import Vue from 'vue';
import App from './App.vue';
import router from './router';
import { trackerInstall } from '@rl521/track-sdk';

// 安装并初始化埋点 SDK
Vue.use(trackerInstall, {
    reportUrl: 'https://your-report-url.com/api/track',
    debug: process.env.NODE_ENV === 'development',
    autoTrack: true
});

new Vue({
    router,
    render: h => h(App)
}).$mount('#app');
```

#### 方式二：默认导入（兼容旧代码）
```javascript
// main.js
import Vue from 'vue';
import App from './App.vue';
import router from './router';
import TrackSdk from '@rl521/track-sdk';

// 安装并初始化埋点 SDK
Vue.use(TrackSdk.trackerInstall, {
    reportUrl: 'https://your-report-url.com/api/track',
    debug: process.env.NODE_ENV === 'development',
    autoTrack: true
});

new Vue({
    router,
    render: h => h(App)
}).$mount('#app');
```

### 3. 核心 API 调用

#### 3.1 设置访问者信息（登录后调用）
```typescript
// 组件内调用
this.$tracker.setVisitor({
    id: 'user123',
    name: '张三',
    phone: '13800138000'
});

// Composition API（Vue3）
import { setVisitor } from '@rl521/track-sdk';
setVisitor({
    id: 'user123',
    name: '张三',
    phone: '13800138000'
});
```

#### 3.2 设置租户信息
```typescript
this.$tracker.setTenant({
    id: 'tenant456',
    name: 'XX公司'
});
// Composition API（Vue3）
import { setTenant } from '@rl521/track-sdk';
setTenant({
    id: 'tenant456',
    name: 'XX公司'
});
```

#### 3.3 设置部门信息
```typescript
this.$tracker.setDepartment({
    id: 'dept789',
    name: '技术部',
    parentId: 'dept001'
});
// Composition API（Vue3）
import { setDepartment } from '@rl521/track-sdk';
setDepartment({
    id: 'dept789',
    name: '技术部',
    parentId: 'dept001'
});
```

#### 3.4 登录后重新加载路由信息
```typescript
// 登录成功后调用，更新路由权限并重新上报当前页面
this.$tracker.reloadRoute();
```

#### 3.5 自定义埋点上报
```typescript
// 自定义事件类型和参数
this.$tracker.track('custom_event', {
    action: 'button_click',
    module: 'home_page',
    content: '首页轮播图点击'
});
```

#### 3.6 销毁埋点实例（退出登录时）
```typescript
this.$tracker.destroy();
```

### 4. 便捷函数调用（无需全局挂载）
```typescript
// 命名导入（推荐）
import {
    initTracker,
    setVisitor,
    track,
    reloadRouteInfo,
    destroyTracker
} from '@rl521/track-sdk';

// 初始化（非全局引入时使用）
initTracker({
    reportUrl: 'https://your-report-url.com/api/track',
    debug: true
});

// 设置访问者信息
setVisitor({ id: 'user123' });

// 自定义埋点
track('custom_event', { action: 'download' });

// 重新加载路由
reloadRouteInfo();

// 销毁实例
destroyTracker();
```

## 配置项说明

| 配置项 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| reportUrl | string | ✅ | - | 埋点数据上报地址 |
| debug | boolean | ❌ | false | 是否开启调试模式（控制台打印埋点数据） |
| autoTrack | boolean | ❌ | true | 是否开启自动埋点（页面访问、按钮点击） |
| extraParams | Record<string, any> | ❌ | {} | 全局公共参数，将附加到所有埋点数据中 |
| reportDelay | number | ❌ | 0 | 上报延迟（ms），默认即时上报 |

## 埋点数据格式
上报的数据格式如下（JSON）：
```json
{
  "eventType": "page_view/click/custom", // 事件类型
  "path": "/home?query=123", // 页面路径
  "title": "首页", // 页面标题
  "timestamp": 1716888888888, // 时间戳
  "visitor": { "id": "user123", "name": "张三" }, // 访问者信息
  "tenant": { "id": "tenant456", "name": "XX公司" }, // 租户信息
  "department": { "id": "dept789", "name": "技术部" }, // 部门信息
  "extra": { "appId": "your-app-id", "action": "button_click" }, // 额外参数
  "elementInfo": { "tagName": "BUTTON", "text": "提交" } // 点击事件元素信息
}
```

## 兼容性
- Vue2：≥ 2.6.0（注：Vue2 已停止维护，建议优先使用 Vue3）
- Vue3：≥ 3.2.0（适配 ESM/CJS 双模块规范）
- VueRouter：≥ 3.0.0（Vue2）、≥ 4.0.0（Vue3）
- 打包工具：Vite、Webpack 均兼容
- 调试方式：支持 `npm link` 本地调试，无导出及时序报错



## 注意事项
1. 上报地址需支持跨域请求，否则会导致上报失败。
2. 自动埋点会过滤表单元素（INPUT/TEXTAREA/SELECT）的点击事件，避免重复上报。
3. 登录后需调用 `setVisitor` 设置访问者信息，确保埋点数据与用户关联。
4. Vue3 中若使用 Composition API，可通过 `inject('tracker')` 获取实例。
5. 已优化依赖配置，解决 `rollup-plugin-terser`、`vue@2.7.16` 等废弃警告，清理冗余依赖。
6. 已修复模块导出报错（TS2459、默认导出缺失、`install is not defined`）、`npm link` 调试报错及 Vue 实例时序报错（读取 prototype 为 undefined）。
7. 推荐使用 **直接命名导入 install 方法**（而非解构），更适配 ESM 规范，彻底避免导出报错。
8. SDK 内部已通过 `onVueLoaded` 回调处理时序问题，无需外部额外等待 Vue 初始化。
9. 本地调试时若仍报错，可尝试删除目标项目 `node_modules/.vite` 缓存后重启开发服务。