@seaverse/track-sdk 0.1.1

package/README.md

@@ -0,0 +1,272 @@
+# @seaverse/track-sdk
+
+统一埋点 SDK，采用 Token 化配置，所有平台配置已内置，使用更简单。
+
+## 特性
+
+- 🎯 **Token 化配置**：只需提供 token，无需关心复杂配置
+- 🔒 **代码混淆**：生产构建自动混淆，保护配置信息
+- 🚀 **智能采集**：自动采集用户行为，同时支持手动埋点
+- 🔌 **多平台支持**：同时支持多个数据分析平台
+- 📦 **TypeScript 支持**：完整的类型定义
+- 🎨 **按需加载**：动态导入，减少初始加载
+
+## 安装
+
+```bash
+npm install @seaverse/track-sdk
+```
+
+安装 SDK 时会自动安装所需依赖。
+
+## 快速开始
+
+### 基本使用
+
+```typescript
+import { TrackClient } from '@seaverse/track-sdk';
+
+// 创建客户端（使用生产环境 token）
+const trackClient = new TrackClient({
+  token: 'prod_2f8a9c1b4e3d',
+});
+
+// 初始化
+await trackClient.initialize();
+
+// 手动埋点
+await trackClient.track('button_click', {
+  button_name: '购买按钮',
+  page: '商品详情',
+});
+```
+
+## API 文档
+
+### TrackClient
+
+#### 构造函数
+
+```typescript
+new TrackClient(config: TrackConfig)
+```
+
+**参数：**
+
+```typescript
+interface TrackConfig {
+  token: string;     // 应用令牌（必填）
+  debug?: boolean;   // 是否开启调试模式，默认 false
+}
+```
+
+#### 方法
+
+##### `initialize(): Promise<void>`
+
+初始化 SDK，必须在使用前调用。
+
+```typescript
+await trackClient.initialize();
+```
+
+##### `track(eventName: string, properties?: EventProperties): Promise<void>`
+
+跟踪事件。
+
+```typescript
+await trackClient.track('purchase', {
+  product_id: '12345',
+  price: 99.99,
+  currency: 'CNY',
+});
+```
+
+##### `setUserId(userId: string): Promise<void>`
+
+设置用户 ID（用户登录时调用）。
+
+```typescript
+await trackClient.setUserId('user_123456');
+```
+
+##### `setUserProperties(properties: UserProperties): Promise<void>`
+
+设置用户属性。
+
+```typescript
+await trackClient.setUserProperties({
+  age: 25,
+  gender: 'male',
+  vip_level: 'gold',
+});
+```
+
+##### `clearUserId(): Promise<void>`
+
+清除用户 ID（用户登出时调用）。
+
+```typescript
+await trackClient.clearUserId();
+```
+
+##### `getInitializedProviders(): TrackProvider[]`
+
+获取已初始化的提供商列表。
+
+```typescript
+const providers = trackClient.getInitializedProviders();
+console.log(providers); // 已初始化的埋点平台列表
+```
+
+## 使用示例
+
+### React 应用
+
+```typescript
+import { useEffect } from 'react';
+import { TrackClient } from '@seaverse/track-sdk';
+
+// 创建全局实例
+const trackClient = new TrackClient({
+  token: process.env.REACT_APP_TRACK_TOKEN || 'dev_9a3b6c2d1e4f',
+  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 应用
+
+```typescript
+// plugins/track.ts
+import { TrackClient } from '@seaverse/track-sdk';
+
+export const trackClient = new TrackClient({
+  token: import.meta.env.VITE_TRACK_TOKEN || 'dev_9a3b6c2d1e4f',
+  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):**
+```bash
+# 开发环境
+REACT_APP_TRACK_TOKEN=dev_9a3b6c2d1e4f
+
+# 测试环境
+REACT_APP_TRACK_TOKEN=test_5d7e2a4b8f1c
+
+# 生产环境
+REACT_APP_TRACK_TOKEN=prod_2f8a9c1b4e3d
+```
+
+**Vue (.env):**
+```bash
+# 开发环境
+VITE_TRACK_TOKEN=dev_9a3b6c2d1e4f
+
+# 生产环境
+VITE_TRACK_TOKEN=prod_2f8a9c1b4e3d
+```
+
+## 最佳实践
+
+### 1. 环境配置
+
+使用环境变量管理 token：
+
+```typescript
+const trackClient = new TrackClient({
+  token: process.env.REACT_APP_TRACK_TOKEN || 'dev_9a3b6c2d1e4f',
+  debug: process.env.NODE_ENV !== 'production',
+});
+```
+
+### 2. 用户生命周期
+
+```typescript
+// 登录
+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. 错误处理
+
+```typescript
+try {
+  await trackClient.initialize();
+} catch (error) {
+  console.error('埋点初始化失败:', error);
+  // 继续运行，不阻塞主流程
+}
+```
+
+## 常见问题
+
+**Q: 如何申请新的 token？**
+
+联系管理员添加新的配置到 `src/config.ts`。
+
+**Q: 如何验证埋点是否正常工作？**
+
+开启 debug 模式：
+```typescript
+const trackClient = new TrackClient({
+  token: 'your_token',
+  debug: true,  // 会在控制台输出日志
+});
+```
+
+## License
+
+MIT