track-point

框架无关的纯 JS 前端打点 SDK，用于在 Vue、React、Nuxt、Next、普通 HTML/JS 项目中统一记录 PV、UV、渠道参数和自定义业务事件。

SDK 不依赖框架，不提供指令、Hook、Provider，也不自动接管路由、生命周期、点击、曝光或请求拦截。业务项目自己选择上报时机，只调用统一 JS API。

背景

不同前端项目经常各自实现打点，容易出现事件格式不统一、渠道参数丢失、PV/UV 口径不一致、上报方式混乱、隐私处理缺失等问题。

track-point 目标是提供一个轻量通用 SDK，把事件结构、项目标识、用户标识、渠道上下文、队列、批量、重试、consent 和上报方式统一起来。

实现方案

• 纯 TypeScript 实现，运行时面向浏览器网页环境。
• 支持 npm 包和 CDN IIFE 产物。
• 默认上报方式为 transport: 'auto'：优先 fetch 接口上报，失败后降级图片上报。
• 支持 fetch、image、custom 三类上报方式。
• fetch/custom 发送完整 JSON；image 只发送短字段白名单，避免 URL 过长和敏感信息进入日志。
• SDK 内部生成 anonymousId 和 sessionId，登录后可用 identify() 关联业务用户。
• 支持 setContext() 写入渠道、租户、页面模块等公共上下文。
• 支持 consent 授权、字段脱敏、URL query 白名单、队列批量、失败重试、离线持久队列。

安装

npm install @boilingwater/[email protected]

快速开始

import TrackPoint from '@boilingwater/track-point'

TrackPoint.init({
  appId: 'vue-web',
  endpoint: 'https://log.example.com/collect',
  transport: 'auto',
  env: import.meta.env.MODE,
  defaultContext: {
    channel: 'web'
  },
  consent: {
    required: true,
    defaultGranted: false,
    deniedBehavior: 'drop'
  }
})

TrackPoint.setConsent(true)

TrackPoint.page('page_view', {
  path: '/home',
  title: '首页'
})

TrackPoint.track('order_submit_success', {
  orderId: 'order_001',
  amount: 99
})

TrackPoint.track('order_submit_success', {
  orderId: 'order_002',
  amount: 199
}, {
  eventType: 'payment'
})

CDN 使用：

<script src="https://unpkg.com/@boilingwater/[email protected]/dist/track-point.iife.js"></script>
<script>
  TrackPoint.init({
    appId: 'vue-web',
    endpoint: 'https://log.example.com/collect',
    transport: 'auto'
  })

  TrackPoint.page('page_view', {
    path: location.pathname,
    title: document.title
  })
</script>

API 清单

TrackPoint.init(config)
TrackPoint.track(eventName, props, options)
TrackPoint.page(pageName, props)
TrackPoint.click(eventName, props)
TrackPoint.exposure(eventName, props)
TrackPoint.identify(userId, traits)
TrackPoint.setUser(user)
TrackPoint.setContext(context)
TrackPoint.startTimer(name, props)
TrackPoint.endTimer(name, props)
TrackPoint.trackDuration(name, duration, props)
TrackPoint.setConsent(granted)
TrackPoint.flush(options)
TrackPoint.inspect()
TrackPoint.destroy()

Vue 简单 Demo

Vue 项目只需要在入口、路由回调、登录回调里主动调用。

// src/track.ts
import TrackPoint from '@boilingwater/track-point'

export function initTrackPoint() {
  const params = new URLSearchParams(window.location.search)

  TrackPoint.init({
    appId: 'vue-web',
    endpoint: 'https://log.example.com/collect',
    transport: 'auto',
    env: import.meta.env.MODE,
    defaultContext: {
      projectType: 'vue',
      channel: params.get('channel') || '',
      utmSource: params.get('utm_source') || '',
      utmMedium: params.get('utm_medium') || '',
      utmCampaign: params.get('utm_campaign') || ''
    },
    consent: {
      required: true,
      defaultGranted: false,
      deniedBehavior: 'drop'
    }
  })
}

export function grantTrackConsent() {
  TrackPoint.setConsent(true)
}

export function trackPageView(to: { path: string; fullPath: string; name?: string | symbol | null }) {
  TrackPoint.page('page_view', {
    path: to.path,
    fullPath: to.fullPath,
    routeName: typeof to.name === 'symbol' ? to.name.description : to.name || '',
    title: document.title
  })
}

export function identifyUser(user: { id: string; level?: string }) {
  TrackPoint.identify(user.id, {
    userLevel: user.level
  })
}

// src/main.ts
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'
import { grantTrackConsent, initTrackPoint, trackPageView } from './track'

initTrackPoint()

// 放在隐私弹窗确认回调里更合适；这里仅演示。
grantTrackConsent()

router.afterEach((to) => {
  trackPageView(to)
})

createApp(App).use(router).mount('#app')

完整示例见 examples/vue3-pvuv-channel.ts。

使用前须知

• 必须配置 appId，后端可通过顶层 appId 和事件内 event.app.appId 判断来源项目。
• 事件名只能使用小写英文、数字和下划线，例如 page_view、order_submit_success。
• 默认不采集 DOM 文本、输入框内容、cookie、token、authorization。
• transport: 'auto' 默认优先接口上报，接口失败后降级图片上报。
• 图片上报默认 URL 长度限制为 1800，只发送短字段和白名单字段；超出后会删除可选的 prop_、ctx_ 参数。
• 复杂 props、订单信息、长文本等请使用接口上报或 custom request。
• 如果开启 consent.required，未调用 setConsent(true) 前不会发送事件。
• SSR/Node 构建阶段可以 import，但请在浏览器端调用 init()。

自定义请求

特殊 WebView、小程序 WebView 或业务统一请求库可以替换默认请求实现：

TrackPoint.init({
  appId: 'vue-web',
  endpoint: 'https://log.example.com/collect',
  transport: 'custom',
  request: ({ url, method, data, headers }) => {
    return appBridge.request({ url, method, data, headers })
  }
})

构建

npm install
npm run typecheck
npm run build

构建产物：

• dist/index.mjs：ESM
• dist/index.cjs：CommonJS
• dist/index.d.ts：类型声明
• dist/track-point.iife.js：CDN 全局变量 TrackPoint

文档

• 完整方案