TrackJS SDK

版本: v0.6.0 适用平台: 微信小程序、Web 浏览器、Node.js

多租户通用埋点 SDK，支持自动采集设备信息、用户行为跟踪、Schema 校验等功能。

核心特性

• ✅ 多平台支持：微信小程序、Web、Node.js
• ✅ 双认证模式：Public Token（客户端）/ HMAC 签名（服务端）
• ✅ 自动采集 30+ Context 字段（v0.6.0）：设备性能、安全区、权限、主题等
• ✅ Schema 校验：类型、必填、Enum、长度、正则等
• ✅ 批量上报：默认每批 20 个事件或每 10 秒自动 flush
• ✅ 失败重试：网络失败时自动重新入队
• ✅ 插件化架构：支持自定义插件扩展功能

快速开始

安装

npm install @cxz-trackjs/trackjs

基础用法

微信小程序：

import { init, createMiniProgramPlugin } from "@cxz/trackjs";

await init({
  endpoint: "https://api.example.com",
  tenantId: "your-tenant-id",
  appId: "your-app-id",
  publicToken: "pk_xxxxx", // 客户端使用 Public Token
  schemaVersion: "v1",
  debug: true,
  plugins: [
    createMiniProgramPlugin({
      mpVersion: "1.0.0",
      autoTrackApp: true,  // 自动采集 App 生命周期
      autoTrackPage: true, // 自动采集 Page 生命周期
    }),
  ],
});

// 手动上报事件
await TrackJS.track("order_pay", {
  order_id: "A123",
  amount: 28.5
});

// 用户识别
await TrackJS.identify("user_12345", {
  name: "张三"
});

Node.js 服务端：

import { init } from "@cxz/trackjs";

await init({
  endpoint: "https://api.example.com",
  tenantId: "your-tenant-id",
  appId: "your-backend-service",
  signingKey: process.env.SIGNING_KEY, // 服务端使用 HMAC 签名
  schemaVersion: "v1",
});

await TrackJS.track("order_created", { order_id: "A123" });

核心 API

| API | 说明 | |-----|------| | init(config) | 初始化 SDK，配置租户、应用、上报地址等 | | track(eventName, properties?) | 上报事件，自动携带租户、SDK 版本、时间戳 | | identify(loginId, traits?) | 用户身份识别，绑定登录 ID | | setWeChatIdentity(openid, unionid?) | 设置微信身份（小程序专用） | | setSuperProperties(props) | 设置公共属性（每个事件都会带上） | | flush() | 立即发送队列中的所有事件 |

Context 字段自动采集（v0.6.0）

SDK 自动采集 30 个 context 字段，包括：

基础字段（11 个）

• 设备信息：device_os, device_model, device_brand, os_version
• 屏幕信息：screen_width, screen_height, window_width, window_height, pixel_ratio
• 微信环境：wechat_version, sdk_base_version
• 其他：network_type, env

新增高价值字段（19 个）⭐

• 设备性能 (2)：abi, benchmark_level（性能等级 0-50）
• 窗口/安全区 (3)：status_bar_height, safe_area, screen_top
• 应用环境 (4)：language, theme, enable_debug, host
• 系统设置 (4)：bluetooth_enabled, location_enabled, wifi_enabled, device_orientation
• 授权状态 (4)：bluetooth_authorized, location_authorized, location_reduced_accuracy, camera_authorized

查看完整字段映射: WECHAT_FIELD_MAPPING.md

兼容性

| SDK 版本 | 基础库要求 | 采集字段数 | 说明 | |---------|-----------|-----------|------| | v0.5.x | 无要求 | 11 个 | 使用旧 API（已废弃） | | v0.6.0 | >= 2.20.1 | 30 个 | 使用微信新 API |

重要提示：

• SDK v0.6.0 要求微信基础库 >= 2.20.1
• 建议在小程序管理后台设置最低基础库版本为 2.20.1
• 如果基础库版本过低，SDK 会记录错误并跳过 context 采集

构建

npm install
npm run build

产物：

• lib/index.js、lib/index.d.ts：供 bundler / npm 引入。
• dist/track.min.js：供 CDN <script> 或小程序远程加载。