@chenweikang/web-sdk

DataTrack 浏览器埋点 SDK，用于接入自研埋点数据上报中台。SDK 支持自动 PV、自定义事件、批量上报、定时 flush、页面卸载时 sendBeacon 兜底。

安装

npm install @chenweikang/web-sdk

初始化

import { initDataTrack } from "@chenweikang/web-sdk";

initDataTrack({
  appKey: "你的项目 AppKey",
  endpoint: "https://tracking.example.com/collect/v1/events",
  autoPageView: true,
  batchSize: 10,
  flushIntervalMs: 5000,
  getContext: () => ({
    app: "web",
    env: import.meta.env.MODE,
  }),
});

自定义事件

import { track } from "@chenweikang/web-sdk";

track("product_detail_view", {
  product_id: "100123",
  product_name: "无线耳机 Pro",
  price: 299,
  source_page: "home",
});

配置项

| 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | appKey | string | 必填 | 后台项目的 AppKey | | endpoint | string | 必填 | 上报接口地址 | | autoPageView | boolean | true | 初始化后是否自动上报 page_view | | batchSize | number | 10 | 批量上报条数 | | flushIntervalMs | number | 5000 | 定时 flush 间隔 | | distinctId | string | 自动生成 | 用户唯一标识 | | sessionId | string | 自动生成 | 会话标识 | | getContext | () => Record<string, unknown> | 无 | 自定义上下文字段 |

注意事项

• 浏览器 SDK 不保存 app_secret。
• Web 上报依赖 app_key + 域名白名单 + 项目状态 + 限流 保护。
• 服务端 HTTP 上报请使用 HMAC 签名。
• DataTrack 平台要求事件先登记并发布，未登记或字段类型不匹配的事件会被后端拒绝。
• 如果没有登记 page_view 事件，请将 autoPageView 设置为 false。