Track SDK

一个通用的埋点 SDK，纯 TS/JS 核心逻辑，不依赖任何前端框架。可用于 Web、Vue、React、小程序与 Node 环境，通过可注入的适配器解决平台差异。

运行与构建

npm install
npm run typecheck
npm run build

构建产物会输出到 dist/。

使用示例

import { createTracker } from "track-sdk-core"

const tracker = await createTracker({
  appId: "demo",
  endpoint: "https://your-endpoint/track",
  batchSize: 20,
  flushInterval: 5000
})

tracker.track("page_view", { page: "/home" })
tracker.identify("user_123", { plan: "pro" })

项目架构

src/
  core/        核心逻辑（队列、会话、采样、批量上报）
  storage/     存储适配（默认小程序 / Web / 内存）
  transport/   传输适配（默认小程序 / fetch）
  adapter/     环境信息适配（路由、设备、上下文）
  types.ts     类型定义
  utils.ts     工具函数
  index.ts     入口导出

设计要点

• 无框架依赖：核心逻辑纯 TS/JS，Vue/React 只需直接调用。
• 平台适配：通过 transport/storage/adapter 注入或默认实现解决差异。
• JSON 存储：队列与用户标识统一存 JSON 字符串。

环境信息采集

SDK 使用一套通用的字段列表来描述环境信息，无论是小程序还是 Web：

| 字段名 | 说明 | 示例 | | :--- | :--- | :--- | | app_version | 应用版本 | "1.0.0" | | app_env | 应用环境 | "release" / "develop" | | os_name | 操作系统 | "iOS", "Android", "MacIntel" | | os_version | 系统版本 | "14.0.1" | | device_model | 设备型号 | "iPhone 12" | | device_manufacturer | 设备厂商 | "Apple" | | screen_width | 屏幕宽度 | 375 | | screen_height | 屏幕高度 | 812 | | network_type | 网络类型 | "wifi", "4g" | | locale | 语言区域 | "zh_CN" |

此外，在初始化时可以通过 context 参数传入自定义字段，这些字段会附加到所有事件中：

const tracker = await createTracker({
  appId: "demo",
  // ...
  context: {
    // 无论传入什么，都会拼接到事件 context 中
    channel: "app_store",
    campaign_id: "2024_summer",
    any_custom_field: "value"
  }
})

自定义适配器

import { createTracker } from "track-sdk-core"

const tracker = await createTracker({
  appId: "demo",
  endpoint: "https://your-endpoint/track",
  transport: {
    send: async (payload) => {
      return { ok: true, status: 200 }
    }
  },
  storage: {
    async getItem(key) {
      return null
    },
    async setItem(key, value) {},
    async removeItem(key) {}
  },
  adapter: {
    now: () => Date.now(),
    getRoute: () => "/",
    getDevice: () => ({ platform: "custom" }),
    getContext: () => ({})
  }
})