@seaverse/track-sdk

统一埋点 SDK，采用 Token 化配置，所有平台配置已内置，使用更简单。

特性

• 🎯 Token 化配置：只需提供 token，无需关心复杂配置
• 🔒 代码混淆：生产构建自动混淆，保护配置信息
• 🚀 智能采集：自动采集用户行为，同时支持手动埋点
• 🔌 多平台支持：同时支持多个数据分析平台
• 📦 TypeScript 支持：完整的类型定义
• 🎨 按需加载：动态导入，减少初始加载

安装

npm install @seaverse/track-sdk

安装 SDK 时会自动安装所需依赖。

快速开始

基本使用

import { TrackClient } from '@seaverse/track-sdk';

// 创建客户端（使用生产环境 token）
const trackClient = new TrackClient({
  token: 'prod_2f8a9c1b4e3d',
  platform: 'web', // h5
  version: '1.0.0',
});

// 初始化
await trackClient.initialize();

// 手动埋点
await trackClient.track('button_click', {
  button_name: '购买按钮',
  page: '商品详情',
});

API 文档

TrackClient

构造函数

new TrackClient(config: TrackConfig)

参数：

interface TrackConfig {
  token: string;     // 应用令牌（必填）
  platform: string;  // 平台类型（必填，如：web、h5、ios、android）
  version: string;   // 应用版本号（必填）
  debug?: boolean;   // 是否开启调试模式，默认 false
}

方法

initialize(): Promise<void>

初始化 SDK，必须在使用前调用。

await trackClient.initialize();

track(eventName: string, properties?: EventProperties): Promise<void>

跟踪事件。

await trackClient.track('purchase', {
  product_id: '12345',
  price: 99.99,
  currency: 'CNY',
});

setUserId(userId: string): Promise<void>

设置用户 ID（用户登录时调用）。

await trackClient.setUserId('user_123456');

setUserProperties(properties: UserProperties): Promise<void>

设置用户属性。

await trackClient.setUserProperties({
  age: 25,
  gender: 'male',
  vip_level: 'gold',
});

clearUserId(): Promise<void>

清除用户 ID（用户登出时调用）。

await trackClient.clearUserId();

getInitializedProviders(): TrackProvider[]

获取已初始化的提供商列表。

const providers = trackClient.getInitializedProviders();
console.log(providers); // 已初始化的埋点平台列表

使用示例

React 应用

import { useEffect } from 'react';
import { TrackClient } from '@seaverse/track-sdk';

// 创建全局实例
const trackClient = new TrackClient({
  token: process.env.REACT_APP_TRACK_TOKEN || 'dev_9a3b6c2d1e4f',
  platform: 'web',
  version: '1.0.0', // 建议从 package.json 读取
  debug: process.env.NODE_ENV === 'development',
});

function App() {
  useEffect(() => {
    // 初始化埋点
    trackClient.initialize().then(() => {
      console.log('Track SDK 已初始化');
    });
  }, []);

  const handleLogin = async (userId: string) => {
    await trackClient.setUserId(userId);
    await trackClient.track('user_login');
  };

  const handlePurchase = async (productId: string, price: number) => {
    await trackClient.track('purchase', {
      product_id: productId,
      price,
      currency: 'CNY',
    });
  };

  return <div>Your App</div>;
}

export default App;

Vue 应用

// plugins/track.ts
import { TrackClient } from '@seaverse/track-sdk';

export const trackClient = new TrackClient({
  token: import.meta.env.VITE_TRACK_TOKEN || 'dev_9a3b6c2d1e4f',
  platform: 'web',
  version: '1.0.0', // 建议从 package.json 读取
  debug: import.meta.env.DEV,
});

// main.ts
import { createApp } from 'vue';
import App from './App.vue';
import { trackClient } from './plugins/track';

const app = createApp(App);

trackClient.initialize();

app.config.globalProperties.$track = trackClient;

app.mount('#app');

环境变量配置

React (.env):

# 开发环境
REACT_APP_TRACK_TOKEN=dev_9a3b6c2d1e4f

# 测试环境
REACT_APP_TRACK_TOKEN=test_5d7e2a4b8f1c

# 生产环境
REACT_APP_TRACK_TOKEN=prod_2f8a9c1b4e3d

Vue (.env):

# 开发环境
VITE_TRACK_TOKEN=dev_9a3b6c2d1e4f

# 生产环境
VITE_TRACK_TOKEN=prod_2f8a9c1b4e3d

最佳实践

1. 环境配置

使用环境变量管理 token：

const trackClient = new TrackClient({
  token: process.env.REACT_APP_TRACK_TOKEN || 'dev_9a3b6c2d1e4f',
  platform: 'web',
  version: '1.0.0',
  debug: process.env.NODE_ENV !== 'production',
});

2. 用户生命周期

// 登录
async function onLogin(userId: string) {
  await trackClient.setUserId(userId);
  await trackClient.setUserProperties({
    login_time: Date.now(),
  });
  await trackClient.track('user_login');
}

// 登出
async function onLogout() {
  await trackClient.track('user_logout');
  await trackClient.clearUserId();
}

3. 错误处理

try {
  await trackClient.initialize();
} catch (error) {
  console.error('埋点初始化失败:', error);
  // 继续运行，不阻塞主流程
}

常见问题

Q: 如何申请新的 token？

联系管理员添加新的配置到 src/config.ts。

Q: 如何验证埋点是否正常工作？

开启 debug 模式：

const trackClient = new TrackClient({
  token: 'your_token',
  platform: 'web',
  version: '1.0.0',
  debug: true,  // 会在控制台输出日志
});

License

MIT