@wlydfe/track

一个现代化的埋点追踪 SDK 封装包，基于 hina-cloud-js-sdk，支持 Web 和 uni-app 小程序平台，提供统一的埋点初始化接口。

✨ 特性

• 🚀 TypeScript 支持 - 完整的类型定义和类型检查
• 📦 ESM 模块 - 原生 ES 模块支持，支持 tree-shaking
• 🌐 多平台支持 - 支持 Web 和 uni-app 小程序平台
• 🔧 现代化工具链 - 使用 unbuild、pnpm、ESLint 等现代工具
• 📚 完整文档 - 自动生成 TypeScript 声明文件和 JSDoc 注释
• 🧪 测试支持 - 集成 Vitest 测试框架
• 🎯 示例项目 - 包含 Vue 3 + Vite 示例项目
• 🔄 热重载开发 - 支持文件监听和热重载开发模式

📦 安装

# 使用 pnpm (推荐)
pnpm add @wlydfe/track

# 使用 npm
npm install @wlydfe/track

# 使用 yarn
yarn add @wlydfe/track

🚀 快速开始

Web 平台

import { initTrack, PlatformType } from '@wlydfe/track'

// 初始化埋点 SDK
const track = initTrack({
  serverUrl: 'https://your-tracking-server.com',
  showLog: true,
  autoTrackConfig: {
    pageviewAutoTrack: 'singlePage',
    pageLeaveAutoTrack: true,
  },
})

// 使用埋点功能
track.track('button_click', {
  button_name: 'submit',
  page: 'home',
})

uni-app 小程序平台

import { initTrack, PlatformType } from '@wlydfe/track'

// 在 App.vue 中初始化
const app = createApp(App)

initTrack({
  serverUrl: 'https://your-tracking-server.com',
  showLog: true,
  platform: PlatformType.UNI_WEAPP,
  app: app,
})

🛠️ 开发指南

环境要求

• Node.js >= 22
• pnpm >= 10.0.0

安装依赖

pnpm install

开发命令

# 开发模式（监听文件变化）
pnpm dev

# 构建项目
pnpm build

# 类型检查
pnpm typecheck

# 代码检查
pnpm lint

# 自动修复代码格式
pnpm lint-fix

# 运行测试
pnpm test

# 发布新版本
pnpm release

项目结构

@wlydfe/track/
├── src/                    # 源代码目录
│   ├── index.ts           # 主入口文件
│   ├── track.ts           # 埋点核心逻辑
│   ├── types.ts           # 类型定义
│   └── config/            # 配置文件
│       └── index.ts       # 默认配置
├── example/               # 示例项目
│   ├── src/              # Vue 示例源码
│   ├── package.json      # 示例项目配置
│   └── vite.config.ts    # Vite 配置
├── scripts/              # 构建脚本
├── build.config.ts       # unbuild 配置
├── tsconfig.json         # TypeScript 配置
├── eslint.config.mts     # ESLint 配置
└── package.json          # 项目配置

📚 API 文档

核心函数

initTrack(config: TrackType): HinaTrack | undefined

初始化埋点 SDK，根据平台类型配置相应的埋点功能。

参数：

• config.serverUrl (string): 采集上报地址 URL
• config.showLog (boolean, 可选): 是否允许控制台打印查看埋点数据，默认 true
• config.platform (PlatformType, 可选): 平台类型，默认 PlatformType.WEB
• config.autoTrackConfig (any, 可选): 埋点配置，默认使用内置配置
• config.app (App | UniAppInstance, 可选): 应用实例，uni-app 小程序需要传递

返回值：

• Web 平台：返回 HinaTrack 实例
• 其他平台：返回 undefined

示例：

import { initTrack, PlatformType } from '@wlydfe/track'

const track = initTrack({
  serverUrl: 'https://track.example.com',
  showLog: true,
  platform: PlatformType.WEB,
})

if (track) {
  track.track('user_action', { action: 'login' })
}

类型定义

PlatformType

平台类型枚举：

enum PlatformType {
  WEB = 'web', // 网页
  UNI_WEAPP = 'uni-weapp', // uni小程序
}

TrackType

埋点配置类型：

interface TrackType {
  serverUrl: string // 采集上报地址URL
  showLog?: boolean // 是否允许控制台打印查看埋点数据
  platform?: PlatformType // 平台类型
  autoTrackConfig?: any // 埋点配置
  app?: App<any> | UniAppInstance // 应用实例
}

UniAppInstance

uni-app 小程序实例类型，包含常用的生命周期方法：

interface UniAppInstance {
  mixin: (options: {
    onLaunch?: (options?: any) => void
    onShow?: (options?: any) => void
    onHide?: () => void
    onUnload?: () => void
    onLoad?: (options?: any) => void
    onTabItemTap?: (options?: any) => void
    onShareAppMessage?: () => void
    onShareTimeline?: () => void
  }) => void
}

默认配置

包内置了 Web 平台的默认埋点配置：

const defaultWebAutoTrackConfig = {
  pageviewAutoTrack: 'singlePage', // 单页面应用页面浏览自动埋点
  pageLeaveAutoTrack: true, // 页面离开自动埋点
}

🧪 测试

项目使用 Vitest 进行测试：

# 运行所有测试
pnpm test

# 监听模式运行测试
pnpm test --watch

# 生成测试覆盖率报告
pnpm test --coverage

📦 构建

项目使用 unbuild 进行构建，支持多种输出格式：

• ESM: dist/index.mjs - 现代 ES 模块
• 类型声明: dist/index.d.mts - TypeScript 类型定义

# 构建项目
pnpm build

# 开发模式构建（监听文件变化）
pnpm dev:watch

# 生成 stub 文件（用于开发）
pnpm dev:stub

🎯 示例项目

项目包含一个完整的 Vue 3 + Vite 示例项目，位于 example/ 目录：

cd example
pnpm install
pnpm dev

示例项目展示了如何在 Vue 3 项目中使用这个埋点包。

📝 发布

自动发布

# 发布新版本（自动更新版本号）
pnpm release

手动发布

# 构建项目
pnpm build

# 发布到 npm
pnpm publish

🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 这个仓库
2. 创建你的特性分支 (git checkout -b feature/AmazingFeature)
3. 提交你的更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开一个 Pull Request

📄 许可证

本项目基于 MIT 许可证开源。

🙏 致谢

• hina-cloud-js-sdk - 埋点数据采集 SDK
• unbuild - 现代化的构建工具
• pnpm - 快速、节省磁盘空间的包管理器
• Vitest - 现代化的测试框架
• Vue - 渐进式 JavaScript 框架

Made with ❤️ by goodswifter