{"_id":"@boilingwater/track-point","_rev":"3-c6c7e448a0080525ad7c0ceda530fdfb","name":"@boilingwater/track-point","dist-tags":{"latest":"0.1.0"},"versions":{"0.0.1":{"name":"@boilingwater/track-point","version":"0.0.1","keywords":["analytics","tracking","pv","uv","channel"],"author":"","license":"UNLICENSED","_id":"@boilingwater/track-point@0.0.1","maintainers":[{"name":"mida","email":"454441207@qq.com"}],"dist":{"shasum":"efde6c0902345ea97fab3edffd620b9fb16cd4ff","tarball":"https://registry.npmjs.org/@boilingwater/track-point/-/track-point-0.0.1.tgz","fileCount":10,"integrity":"sha512-trSJ7Zaydb+bn5dQ/g6I6jEvoxFTmXRh5AnAZS0yDFTo3jPB6ePCLLWmeyh4QWeqDnISVkQOhKgOhSIlfffGnQ==","signatures":[{"sig":"MEQCIFxXyM6PpcB5q3qqrnCfaeAdMkfmnVZ+R8tM2Db5jXzTAiB9ff6GeYVuyXFo1zo8+KffjQQjq66w8dH0kpYIEPVJXw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":205877},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","unpkg":"./dist/track-point.iife.js","module":"./dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.cjs"}},"gitHead":"d0269b0f01184f0a3e6a64e1fdb73788e0c353b3","scripts":{"lint":"tsc --noEmit","build":"tsup","typecheck":"tsc --noEmit"},"_npmUser":{"name":"mida","email":"454441207@qq.com"},"jsdelivr":"./dist/track-point.iife.js","_npmVersion":"11.6.2","description":"Framework-agnostic frontend tracking SDK for page views, users, channels, and custom events.","directories":{},"_nodeVersion":"25.2.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","typescript":"^5.8.3"},"_npmOperationalInternal":{"tmp":"tmp/track-point_0.0.1_1780658640059_0.33491160116175633","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@boilingwater/track-point","version":"0.0.2","keywords":["analytics","tracking","pv","uv","channel"],"author":"","license":"UNLICENSED","_id":"@boilingwater/track-point@0.0.2","maintainers":[{"name":"mida","email":"454441207@qq.com"}],"dist":{"shasum":"eab55e62da66c63763900bd21e9ad61278502702","tarball":"https://registry.npmjs.org/@boilingwater/track-point/-/track-point-0.0.2.tgz","fileCount":10,"integrity":"sha512-v/pzDUgGbYmtiWZwfg7cNMAKaZml7EToV0cltC5E6Kaaun2QSVHEqcV4l51QI1VHrDnKHnf2Jh7nyAfOg+LAOw==","signatures":[{"sig":"MEQCIA8d3Xsjp6WJ3lkyvMEk7irqxNkiBDzQihRZK2mck8bPAiAyu2uKO34rQTH7QPW/n1XPUl3aISzYlYrRsyhlf7QuIQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":206162},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","unpkg":"./dist/track-point.iife.js","module":"./dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.cjs"}},"gitHead":"fa9aad313c2c3f6040a9aa2a987f627e27d6fdc6","scripts":{"lint":"tsc --noEmit","build":"tsup","typecheck":"tsc --noEmit"},"_npmUser":{"name":"mida","email":"454441207@qq.com"},"jsdelivr":"./dist/track-point.iife.js","_npmVersion":"11.6.2","description":"Framework-agnostic frontend tracking SDK for page views, users, channels, and custom events.","directories":{},"_nodeVersion":"25.2.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","typescript":"^5.8.3"},"_npmOperationalInternal":{"tmp":"tmp/track-point_0.0.2_1780659780622_0.5002743359208333","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@boilingwater/track-point","version":"0.1.0","description":"Framework-agnostic frontend tracking SDK for page views, users, channels, and custom events.","type":"module","main":"./dist/index.cjs","module":"./dist/index.mjs","types":"./dist/index.d.ts","unpkg":"./dist/track-point.iife.js","jsdelivr":"./dist/track-point.iife.js","publishConfig":{"access":"public"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.cjs"}},"scripts":{"build":"tsup","typecheck":"tsc --noEmit","lint":"tsc --noEmit"},"keywords":["analytics","tracking","pv","uv","channel"],"author":"","license":"UNLICENSED","devDependencies":{"tsup":"^8.5.0","typescript":"^5.8.3"},"gitHead":"791a7dccb58c5247fda3476e42c950a46b04df60","_id":"@boilingwater/track-point@0.1.0","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-2aY6wiQGI+QppAmtw2SBFKddNy0CpxW3/+UZiGiP+gkKN7javyq+jEuByQwZhvsVtSx/p9JZbS2YB2nO7++mug==","shasum":"bf0f555ecbe1ff6858b395888e4ae2c7884e90bf","tarball":"https://registry.npmjs.org/@boilingwater/track-point/-/track-point-0.1.0.tgz","fileCount":10,"unpackedSize":207105,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDvpTyM/KQ+9Tlo1ZkZoGwlcugyx2fxmWKuE7OCIfhcXwIgahh403nTNORBz/SAnu9ZtRQx+AF50rK32FgKM15LJZs="}]},"_npmUser":{"name":"mida","email":"454441207@qq.com"},"directories":{},"maintainers":[{"name":"mida","email":"454441207@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/track-point_0.1.0_1780999956303_0.8832564161571981"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-05T11:23:59.864Z","modified":"2026-06-09T10:12:36.637Z","0.0.1":"2026-06-05T11:24:00.219Z","0.0.2":"2026-06-05T11:43:00.757Z","0.1.0":"2026-06-09T10:12:36.503Z"},"license":"UNLICENSED","keywords":["analytics","tracking","pv","uv","channel"],"description":"Framework-agnostic frontend tracking SDK for page views, users, channels, and custom events.","maintainers":[{"name":"mida","email":"454441207@qq.com"}],"readme":"# track-point\n\n框架无关的纯 JS 前端打点 SDK，用于在 Vue、React、Nuxt、Next、普通 HTML/JS 项目中统一记录 PV、UV、渠道参数和自定义业务事件。\n\nSDK 不依赖框架，不提供指令、Hook、Provider，也不自动接管路由、生命周期、点击、曝光或请求拦截。业务项目自己选择上报时机，只调用统一 JS API。\n\n## 背景\n\n不同前端项目经常各自实现打点，容易出现事件格式不统一、渠道参数丢失、PV/UV 口径不一致、上报方式混乱、隐私处理缺失等问题。\n\n`track-point` 目标是提供一个轻量通用 SDK，把事件结构、项目标识、用户标识、渠道上下文、队列、批量、重试、consent 和上报方式统一起来。\n\n## 实现方案\n\n- 纯 TypeScript 实现，运行时面向浏览器网页环境。\n- 支持 npm 包和 CDN IIFE 产物。\n- 默认上报方式为 `transport: 'auto'`：优先 `fetch` 接口上报，失败后降级图片上报。\n- 支持 `fetch`、`image`、`custom` 三类上报方式。\n- `fetch/custom` 发送完整 JSON；`image` 只发送短字段白名单，避免 URL 过长和敏感信息进入日志。\n- SDK 内部生成 `anonymousId` 和 `sessionId`，登录后可用 `identify()` 关联业务用户。\n- 支持 `setContext()` 写入渠道、租户、页面模块等公共上下文。\n- 支持 consent 授权、字段脱敏、URL query 白名单、队列批量、失败重试、离线持久队列。\n\n## 安装\n\n```bash\nnpm install @boilingwater/track-point@0.1.0\n```\n\n## 快速开始\n\n```ts\nimport TrackPoint from '@boilingwater/track-point'\n\nTrackPoint.init({\n  appId: 'vue-web',\n  endpoint: 'https://log.example.com/collect',\n  transport: 'auto',\n  env: import.meta.env.MODE,\n  defaultContext: {\n    channel: 'web'\n  },\n  consent: {\n    required: true,\n    defaultGranted: false,\n    deniedBehavior: 'drop'\n  }\n})\n\nTrackPoint.setConsent(true)\n\nTrackPoint.page('page_view', {\n  path: '/home',\n  title: '首页'\n})\n\nTrackPoint.track('order_submit_success', {\n  orderId: 'order_001',\n  amount: 99\n})\n\nTrackPoint.track('order_submit_success', {\n  orderId: 'order_002',\n  amount: 199\n}, {\n  eventType: 'payment'\n})\n```\n\nCDN 使用：\n\n```html\n<script src=\"https://unpkg.com/@boilingwater/track-point@0.1.0/dist/track-point.iife.js\"></script>\n<script>\n  TrackPoint.init({\n    appId: 'vue-web',\n    endpoint: 'https://log.example.com/collect',\n    transport: 'auto'\n  })\n\n  TrackPoint.page('page_view', {\n    path: location.pathname,\n    title: document.title\n  })\n</script>\n```\n\n## API 清单\n\n```ts\nTrackPoint.init(config)\nTrackPoint.track(eventName, props, options)\nTrackPoint.page(pageName, props)\nTrackPoint.click(eventName, props)\nTrackPoint.exposure(eventName, props)\nTrackPoint.identify(userId, traits)\nTrackPoint.setUser(user)\nTrackPoint.setContext(context)\nTrackPoint.startTimer(name, props)\nTrackPoint.endTimer(name, props)\nTrackPoint.trackDuration(name, duration, props)\nTrackPoint.setConsent(granted)\nTrackPoint.flush(options)\nTrackPoint.inspect()\nTrackPoint.destroy()\n```\n\n## Vue 简单 Demo\n\nVue 项目只需要在入口、路由回调、登录回调里主动调用。\n\n```ts\n// src/track.ts\nimport TrackPoint from '@boilingwater/track-point'\n\nexport function initTrackPoint() {\n  const params = new URLSearchParams(window.location.search)\n\n  TrackPoint.init({\n    appId: 'vue-web',\n    endpoint: 'https://log.example.com/collect',\n    transport: 'auto',\n    env: import.meta.env.MODE,\n    defaultContext: {\n      projectType: 'vue',\n      channel: params.get('channel') || '',\n      utmSource: params.get('utm_source') || '',\n      utmMedium: params.get('utm_medium') || '',\n      utmCampaign: params.get('utm_campaign') || ''\n    },\n    consent: {\n      required: true,\n      defaultGranted: false,\n      deniedBehavior: 'drop'\n    }\n  })\n}\n\nexport function grantTrackConsent() {\n  TrackPoint.setConsent(true)\n}\n\nexport function trackPageView(to: { path: string; fullPath: string; name?: string | symbol | null }) {\n  TrackPoint.page('page_view', {\n    path: to.path,\n    fullPath: to.fullPath,\n    routeName: typeof to.name === 'symbol' ? to.name.description : to.name || '',\n    title: document.title\n  })\n}\n\nexport function identifyUser(user: { id: string; level?: string }) {\n  TrackPoint.identify(user.id, {\n    userLevel: user.level\n  })\n}\n```\n\n```ts\n// src/main.ts\nimport { createApp } from 'vue'\nimport App from './App.vue'\nimport router from './router'\nimport { grantTrackConsent, initTrackPoint, trackPageView } from './track'\n\ninitTrackPoint()\n\n// 放在隐私弹窗确认回调里更合适；这里仅演示。\ngrantTrackConsent()\n\nrouter.afterEach((to) => {\n  trackPageView(to)\n})\n\ncreateApp(App).use(router).mount('#app')\n```\n\n完整示例见 [examples/vue3-pvuv-channel.ts](./examples/vue3-pvuv-channel.ts)。\n\n## 使用前须知\n\n- 必须配置 `appId`，后端可通过顶层 `appId` 和事件内 `event.app.appId` 判断来源项目。\n- 事件名只能使用小写英文、数字和下划线，例如 `page_view`、`order_submit_success`。\n- 默认不采集 DOM 文本、输入框内容、cookie、token、authorization。\n- `transport: 'auto'` 默认优先接口上报，接口失败后降级图片上报。\n- 图片上报默认 URL 长度限制为 `1800`，只发送短字段和白名单字段；超出后会删除可选的 `prop_`、`ctx_` 参数。\n- 复杂 `props`、订单信息、长文本等请使用接口上报或 custom request。\n- 如果开启 `consent.required`，未调用 `setConsent(true)` 前不会发送事件。\n- SSR/Node 构建阶段可以 import，但请在浏览器端调用 `init()`。\n\n## 自定义请求\n\n特殊 WebView、小程序 WebView 或业务统一请求库可以替换默认请求实现：\n\n```ts\nTrackPoint.init({\n  appId: 'vue-web',\n  endpoint: 'https://log.example.com/collect',\n  transport: 'custom',\n  request: ({ url, method, data, headers }) => {\n    return appBridge.request({ url, method, data, headers })\n  }\n})\n```\n\n## 构建\n\n```bash\nnpm install\nnpm run typecheck\nnpm run build\n```\n\n构建产物：\n\n- `dist/index.mjs`：ESM\n- `dist/index.cjs`：CommonJS\n- `dist/index.d.ts`：类型声明\n- `dist/track-point.iife.js`：CDN 全局变量 `TrackPoint`\n\n## 文档\n\n- [完整方案](./docs/track-point完整方案.md)\n","readmeFilename":"README.md"}