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> 或小程序远程加载。