track-hub - Web 版本

跨平台前端埋点 SDK 的 Web/TypeScript 实现。

安装

npm install track-hub

使用方法

方式一：单例模式（推荐）

在应用入口初始化，然后在任何地方使用：

// ========== 在应用入口（如 main.ts）初始化 ==========
import { initSDK } from 'track-hub';

// 初始化 SDK（只需要调用一次）
initSDK({
  appKey: 'your-app-key',
  appSecret: 'your-app-secret',
  apiUrl: 'https://api.example.com/track',
  userId: 'user-123',
  anonymousId: 'anon-456',
  // 批量上报配置（可选）
  enableBatch: true,      // 是否启用批量上报，默认 true
  batchSize: 100,         // 批量上报的最大条数，默认 100
  batchInterval: 5000,    // 批量上报的时间间隔（毫秒），默认 5000（5秒）
  // 页面浏览自动追踪配置（可选）
  autoTrackPageView: true,        // 是否自动记录页面浏览，默认 false
  minPageViewDuration: 1000,     // 页面浏览最小时长（毫秒），默认 1000（1秒）
  // Debug 模式配置（可选）
  debug: true,                    // 是否启用 debug 模式，默认 false。启用后会在控制台输出关键日志
});

// ========== 在其他模块中使用 ==========
import { track, setUserId, refreshInfo } from 'track-hub';

// 上报事件（自动批量上报，SDK 内部自动判断何时上报）
track('click_button', {
  event_name: '按钮点击',
  event_value: 'submit',
  properties: {
    button_id: 'submit-btn',
    page: 'home',
  },
});

// 如果需要立即上报，可以传入第三个参数（需要通过 getSDK 获取实例）
import { getSDK } from 'track-hub';
await getSDK().track('important_event', {
  event_name: '重要事件',
}, true); // true 表示立即上报

// 更新用户 ID
setUserId('new-user-id');

// 刷新设备信息和页面信息（页面切换时调用）
refreshInfo();

方式二：直接实例化

如果需要多个实例或更灵活的控制：

import { TrackSDK, WebAdapter } from 'track-hub';

// 初始化 SDK
const sdk = new TrackSDK(
  {
    appKey: 'your-app-key',
    appSecret: 'your-app-secret',
    apiUrl: 'https://api.example.com/track',
    userId: 'user-123',
    anonymousId: 'anon-456',
  },
  new WebAdapter()
);

// 上报事件
await sdk.track('click_button', {
  event_name: '按钮点击',
  event_value: 'submit',
  properties: {
    button_id: 'submit-btn',
    page: 'home',
  },
});

API 文档

单例模式 API（推荐）

initSDK(config, adapter?)

初始化 SDK 单例实例。

import { initSDK } from 'track-hub';

initSDK({
  appKey: 'your-app-key',
  appSecret: 'your-app-secret',
  apiUrl: 'https://api.example.com/track',
  userId: 'user-123',
});

• config: SDK 配置对象
• adapter: 可选，平台适配器，默认使用 WebAdapter

track() - 上报事件（推荐）

直接上报事件，无需获取 SDK 实例。

import { track } from 'track-hub';

await track('event_code', { event_name: '事件名称' });

getSDK()

获取 SDK 实例。如果未初始化会抛出错误。

import { getSDK } from 'track-hub';

const sdk = getSDK();
// 可以访问 SDK 的所有方法
await sdk.track('event_code', { event_name: '事件名称' });

isSDKInitialized()

检查 SDK 是否已初始化。

import { isSDKInitialized, track } from 'track-hub';

if (isSDKInitialized()) {
  await track('event_code', {});
}

destroySDK()

销毁 SDK 实例，用于重新初始化。会自动上报队列中剩余的事件。

import { destroySDK, initSDK } from 'track-hub';

destroySDK();
initSDK({ /* 新配置 */ });

flushSDK()

立即上报队列中的所有事件。

import { flushSDK } from 'track-hub';

// 页面关闭前上报剩余事件
window.addEventListener('beforeunload', () => {
  flushSDK();
});

getSDKQueueSize()

获取队列中待上报的事件数量。

import { getSDKQueueSize } from 'track-hub';

const queueSize = getSDKQueueSize();
console.log(`待上报事件数: ${queueSize}`);

便捷方法

以下方法可以直接调用，无需先获取 SDK 实例：

• track(eventCode, eventData?, immediate?) - 上报事件

  import { track } from 'track-hub';
  await track('event_code', { event_name: '事件名称' });

• setUserId(userId) - 设置用户 ID

  import { setUserId } from 'track-hub';
  setUserId('user-123');

• setAnonymousId(anonymousId) - 设置匿名 ID

  import { setAnonymousId } from 'track-hub';
  setAnonymousId('anon-456');

• setUserProperties(properties) - 设置用户属性

  import { setUserProperties } from 'track-hub';
  setUserProperties({ age: 25, gender: 'male' });

• refreshInfo() - 刷新设备信息和页面信息

  import { refreshInfo } from 'track-hub';
  refreshInfo();

• getSessionId() - 获取会话 ID

  import { getSessionId } from 'track-hub';
  const sessionId = getSessionId();

• startNewSession() - 开始新会话

  import { startNewSession } from 'track-hub';
  startNewSession();

TrackSDK 类

构造函数

new TrackSDK(config: SDKConfig, adapter: PlatformAdapter)

方法

• track(eventCode: string, eventData?: Partial<EventData>, immediate?: boolean): Promise<void> - 上报事件
  • eventCode: 事件代码
  • eventData: 事件数据（可选）
  • immediate: 是否立即上报，默认 false（使用批量上报）
• setUserId(userId: string): void - 更新用户 ID
• setAnonymousId(anonymousId: string): void - 更新匿名 ID
• updateConfig(partialConfig: Partial<SDKConfig>): void - 更新配置
• refreshInfo(): void - 刷新设备信息和页面信息
• flush(): Promise<void> - 立即上报队列中的所有事件
• getQueueSize(): number - 获取队列中待上报的事件数量
• destroy(): void - 清理资源，会自动上报剩余事件

WebAdapter

Web 平台适配器，自动收集浏览器环境信息。

批量上报功能

SDK 默认启用批量上报功能，会自动将事件缓存到队列中，并在以下情况下自动上报：

1. 达到批量大小：当队列中的事件数量达到 batchSize（默认 100 条）时，立即上报
2. 定时上报：每隔 batchInterval（默认 5 秒）自动上报一次
3. 手动上报：调用 flush() 或 flushSDK() 立即上报

批量上报配置

initSDK({
  appKey: 'your-app-key',
  appSecret: 'your-app-secret',
  apiUrl: 'https://api.example.com/track',
  // 批量上报配置
  enableBatch: true,      // 是否启用批量上报，默认 true
  batchSize: 100,         // 批量上报的最大条数，默认 100
  batchInterval: 5000,    // 批量上报的时间间隔（毫秒），默认 5000（5秒）
});

批量上报格式

批量上报时，请求体格式为数组（直接是数组，不需要 events 键）：

[
  { "c": "event_code_1", "t": 1234567890, "p": "payload1" },
  { "c": "event_code_2", "t": 1234567891, "p": "payload2" },
  // ... 最多 100 条
]

使用示例

import { initSDK, track, flushSDK, getSDK } from 'track-hub';

// 初始化
initSDK({
  appKey: 'your-app-key',
  appSecret: 'your-app-secret',
  apiUrl: 'https://api.example.com/track',
  enableBatch: true,
  batchSize: 100,
  batchInterval: 5000,
});

// 正常上报（会自动批量）
track('click_button', { event_name: '按钮点击' });
track('page_view', { event_name: '页面浏览' });

// 立即上报（重要事件，需要使用 getSDK 获取实例）
await getSDK().track('payment_success', { 
  event_name: '支付成功' 
}, true);

// 页面关闭前上报剩余事件
window.addEventListener('beforeunload', () => {
  flushSDK();
});

Debug 模式

SDK 支持 debug 模式，启用后会在控制台输出关键日志，方便开发和调试。

启用 Debug 模式

import { initSDK } from 'track-hub';

initSDK({
  appKey: 'your-app-key',
  appSecret: 'your-app-secret',
  apiUrl: 'https://api.example.com/track',
  debug: true,  // 启用 debug 模式
});

Debug 模式输出的日志

启用 debug 模式后，SDK 会在以下关键位置输出日志：

1. SDK 初始化

   • SDK 配置信息（AppKey、API URL、批量上报配置等）

2. 事件上报

   • 事件创建和验证
   • 事件添加到队列
   • 立即上报和批量上报的成功/失败
   • 上报重试信息

3. 批量上报

   • 批量上报触发（达到批量大小或定时触发）
   • 批量上报成功/失败
   • 队列大小变化

4. 用户信息更新

   • 用户 ID、匿名 ID 更新
   • 用户属性更新

5. 插件管理

   • 插件注册、安装、卸载

6. 错误信息

   • 所有错误都会输出（不受 debug 模式影响）

动态开启/关闭 Debug 模式

import { getSDK } from 'track-hub';

const sdk = getSDK();

// 开启 debug 模式
sdk.updateConfig({ debug: true });

// 关闭 debug 模式
sdk.updateConfig({ debug: false });

日志格式

所有日志都带有 [TrackSDK] 前缀，方便在控制台中识别和过滤。

[TrackSDK] SDK 初始化成功 { appKey: 'xxx', apiUrl: 'xxx', ... }
[TrackSDK] 事件已添加到队列，当前队列大小: 5
[TrackSDK] 开始批量上报，事件数量: 10
[TrackSDK] 批量上报成功，已上报事件数: 10

插件系统

SDK 支持插件机制，可以扩展功能。目前内置了页面浏览自动追踪插件。

页面浏览自动追踪插件

自动记录和上报页面浏览情况，支持：

• 自动追踪：页面加载、路由变化、前进/后退
• 浏览时长：自动记录页面浏览时长
• 多种路由：支持 Hash 路由和 History API 路由

使用方式

方式一：通过配置启用（推荐）

import { initSDK } from 'track-hub';

initSDK({
  appKey: 'your-app-key',
  appSecret: 'your-app-secret',
  apiUrl: 'https://api.example.com/track',
  autoTrackPageView: true,        // 启用自动页面浏览追踪
  minPageViewDuration: 1000,     // 页面浏览最小时长（毫秒）
});

方式二：手动注册插件

import { initSDK, getSDK, PageViewPlugin } from 'track-hub';

// 初始化 SDK
initSDK({
  appKey: 'your-app-key',
  appSecret: 'your-app-secret',
  apiUrl: 'https://api.example.com/track',
});

// 手动注册页面浏览插件
const sdk = getSDK();
const pageViewPlugin = new PageViewPlugin({
  minPageViewDuration: 2000, // 2秒
});
sdk.getPluginManager().register(pageViewPlugin);

插件配置

• autoTrackPageView: 是否自动记录页面浏览，默认 false
• minPageViewDuration: 页面浏览最小时长（毫秒），默认 1000（1秒），只有浏览时长超过此值才上报

上报的事件

1. page_view - 页面浏览事件

   • 触发时机：页面加载、路由变化
   • 包含信息：页面 URL、标题、路径、referrer 等

2. page_view_duration - 页面浏览时长事件

   • 触发时机：页面切换、页面隐藏、页面卸载
   • 包含信息：浏览时长（毫秒）

插件管理

import { getSDK } from 'track-hub';

const sdk = getSDK();
const pluginManager = sdk.getPluginManager();

// 获取插件
const pageViewPlugin = pluginManager.getPlugin('PageViewPlugin');

// 启用/禁用插件
pluginManager.enablePlugin('PageViewPlugin');
pluginManager.disablePlugin('PageViewPlugin');

// 卸载插件
pluginManager.unregister('PageViewPlugin');

自定义插件

你可以创建自定义插件：

import { Plugin, TrackSDK } from 'track-hub';

class CustomPlugin implements Plugin {
  name = 'CustomPlugin';
  private sdk: TrackSDK | null = null;
  private enabled = false;

  install(sdk: TrackSDK): void {
    this.sdk = sdk;
    this.enabled = true;
    // 实现你的插件逻辑
  }

  uninstall(): void {
    // 清理资源
    this.enabled = false;
    this.sdk = null;
  }

  isEnabled(): boolean {
    return this.enabled;
  }

  enable(): void {
    this.enabled = true;
  }

  disable(): void {
    this.enabled = false;
  }
}

// 注册自定义插件
const sdk = getSDK();
sdk.getPluginManager().register(new CustomPlugin());

License

MIT