{"_id":"@boses/litetrack-sdk","_rev":"2-d3e02749a95b425cd15487dd3b59d128","name":"@boses/litetrack-sdk","dist-tags":{"latest":"1.1.1"},"versions":{"1.1.0":{"name":"@boses/litetrack-sdk","version":"1.1.0","keywords":["analytics","tracking","pageviews","statistics","sdk"],"license":"MIT","_id":"@boses/litetrack-sdk@1.1.0","maintainers":[{"name":"cs-xy","email":"1123598783@qq.com"}],"dist":{"shasum":"f599fb6dda4567073c3d3993a15edfc2fc51eb89","tarball":"https://registry.npmjs.org/@boses/litetrack-sdk/-/litetrack-sdk-1.1.0.tgz","fileCount":7,"integrity":"sha512-8mvkSDvFXsIhJlvb45qz4Q3ZQSxi53/BhdBU+NcoJ9YHcoyt4K6WC6wx6cZOzZyM74gQz3D+LPleOk+3SHS3Mg==","signatures":[{"sig":"MEYCIQDDjXFsuhywfsAOexNhxACgIErSIHboAA3hAdQA1n4dYAIhAJV23eNIhprV9ak0dhnF65YljjejG0nBEQsaJcGFP26H","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":53665},"type":"module","types":"./dist/index.d.mts","exports":{".":{"types":"./dist/index.d.mts","import":"./dist/index.mjs"},"./package.json":"./package.json"},"gitHead":"69e67c1b5baeb275e1e8ab5032e308d6b3e26c05","scripts":{"dev":"tsdown --watch","lint":"eslint src","test":"vitest run","build":"tsdown","type-check":"tsc --noEmit","publish-sdk":"node scripts/publish.mjs"},"_npmUser":{"name":"cs-xy","email":"1123598783@qq.com"},"_npmVersion":"10.9.2","description":"LiteTrack analytics SDK - lightweight and framework-agnostic","directories":{},"_nodeVersion":"22.14.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^10.0.3","tsdown":"^0.18.1","vitest":"^4.0.18","globals":"^16.5.0","@eslint/js":"^10.0.1","typescript":"^5.9.3","typescript-eslint":"^8.56.1"},"_npmOperationalInternal":{"tmp":"tmp/litetrack-sdk_1.1.0_1781921176846_0.6975607773303321","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"name":"@boses/litetrack-sdk","version":"1.1.1","description":"LiteTrack analytics SDK - lightweight and framework-agnostic","repository":{"type":"git","url":"git+https://github.com/bosens-China/LiteTrack.git","directory":"apps/sdk"},"homepage":"https://github.com/bosens-China/LiteTrack/tree/master/apps/sdk#readme","bugs":{"url":"https://github.com/bosens-China/LiteTrack/issues"},"type":"module","exports":{".":{"import":"./dist/index.mjs","types":"./dist/index.d.mts"},"./package.json":"./package.json"},"types":"./dist/index.d.mts","scripts":{"build":"tsdown","dev":"tsdown --watch","type-check":"tsc --noEmit","lint":"eslint src","test":"vitest run","publish-sdk":"node scripts/publish.mjs"},"publishConfig":{"access":"public"},"devDependencies":{"@eslint/js":"^10.0.1","eslint":"^10.0.3","globals":"^16.5.0","tsdown":"^0.18.1","typescript":"^5.9.3","typescript-eslint":"^8.56.1","vitest":"^4.0.18"},"keywords":["analytics","tracking","pageviews","statistics","sdk"],"license":"MIT","gitHead":"a10ffb5fea08536e7938644a5464c591101e0a3b","_id":"@boses/litetrack-sdk@1.1.1","_nodeVersion":"24.16.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-vuM8LQKK+ULjJZ55gWYW9mudQH9/9mRXqANYvmETk9p7FmKxJ+p5q7V0TnHdYkEDfsREtpE1ot8/hmF9gwfPbg==","shasum":"631aea5a1a7a0c2ce9659b21d4e7ef0b9004713f","tarball":"https://registry.npmjs.org/@boses/litetrack-sdk/-/litetrack-sdk-1.1.1.tgz","fileCount":7,"unpackedSize":58119,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@boses%2flitetrack-sdk@1.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC8Jx2sTOzAgXq2NRanDCnkHY5jrOB7o9qJe96zN1036AIhAImcN5G8hj4CibsQnYOFi9lw+fuGE/1bO79jiUZQjpCK"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:e701ef35-4707-4a4b-b44a-0e3ab7d44e46"}},"directories":{},"maintainers":[{"name":"cs-xy","email":"1123598783@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/litetrack-sdk_1.1.1_1781942901457_0.37011022662301474"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-20T02:06:16.677Z","modified":"2026-06-20T08:08:21.960Z","1.1.0":"2026-06-20T02:06:16.994Z","1.1.1":"2026-06-20T08:08:21.645Z"},"license":"MIT","keywords":["analytics","tracking","pageviews","statistics","sdk"],"description":"LiteTrack analytics SDK - lightweight and framework-agnostic","maintainers":[{"name":"cs-xy","email":"1123598783@qq.com"}],"readme":"# LiteTrack SDK\n\n面向浏览器环境的轻量统计 SDK，当前调用面围绕 `create()` 展开。\n\n## 设计目标\n\n- 默认调用简单\n- 对 SPA 友好\n- 不默认把数据发到官方域名\n- 提供最小可诊断能力\n\n## 快速开始\n\n```ts\nconst tracker = LiteTrack.create({\n siteToken: 'st_xxx',\n baseUrl: 'https://your-api.com',\n autoPageview: true,\n autoReadProgress: true,\n});\n```\n\n`baseUrl` 必填，只需填服务器源（如 `https://your-api.com`），**不要**带 `/litetrack/v1` 前缀。SDK 会自动拼接 API 契约前缀。注意：API 契约版本与 SDK 语义化版本**刻意解耦**——契约前缀由源码 `src/core/version.ts` 的 `API_VERSION` 常量显式声明（当前为 `v1`），**不随 SDK 大版本号变化**。只有后端上报协议发生破坏性变更时才会手动迁移到 `v2`。SDK 不再内置默认线上地址。\n\n## 浏览器 script 引入\n\n```html\n\n\n```\n\n## API\n\n### `LiteTrack.create(options)`\n\n```ts\nconst tracker = LiteTrack.create({\n siteToken: 'st_xxx',\n baseUrl: 'https://your-api.com',\n autoPageview: true,\n autoReadProgress: true,\n readProgressMilestones: [25, 50, 75, 100],\n identity: {\n visitorId: 'visitor_123',\n sessionId: 'session_456',\n },\n debug: false,\n onError(error) {\n console.error('[LiteTrack]', error);\n },\n});\n```\n\n参数说明：\n\n| 参数 | 说明 |\n| ------------------------ | ----------------------------------------------------------------------------------- |\n| `siteToken` | 站点令牌，必填 |\n| `baseUrl` | API 服务器源，必填，例如 `https://your-api.com`（不带版本前缀，SDK 自动按版本拼接） |\n| `autoPageview` | 默认 `true`，创建后自动上报首屏 PV |\n| `autoReadProgress` | 默认 `false`，自动监听滚动与离开事件 |\n| `readProgressMilestones` | 阅读深度里程碑，默认 `[25, 50, 75, 100]` |\n| `identity` | 可选，外部传入 `visitorId` / `sessionId` |\n| `debug` | 默认 `false`，开启后会把 SDK 错误输出到控制台 |\n| `onError` | SDK 内部请求失败时的回调 |\n\n## Tracker 方法\n\n### `tracker.page(input?)`\n\n```ts\ntracker.page();\n\ntracker.page({\n path: '/posts/hello',\n title: 'Hello World',\n});\n```\n\n### `tracker.read(input)`\n\n```ts\ntracker.read(80);\n\ntracker.read({\n path: '/posts/hello',\n percent: 80,\n});\n```\n\n### `tracker.navigate(input)`\n\n用于 SPA 路由切换。\n\n```ts\ntracker.navigate({\n path: '/posts/hello',\n title: 'Hello World',\n});\n```\n\n也可以精细控制：\n\n```ts\ntracker.navigate({\n path: '/posts/hello',\n title: 'Hello World',\n trackPageview: true,\n resetReadProgress: true,\n});\n```\n\n### `tracker.identify(identity)`\n\n```ts\ntracker.identify({\n visitorId: 'visitor_123',\n sessionId: 'session_456',\n});\n```\n\n### `tracker.stats.site()`\n\n```ts\nconst siteStats = await tracker.stats.site();\n```\n\n返回：\n\n```ts\n{\n totalViews: number;\n totalPages: number;\n}\n```\n\n### `tracker.stats.page(path)`\n\n```ts\nconst pageStats = await tracker.stats.page('/posts/hello');\n```\n\n返回：\n\n```ts\n{\n path: string;\n count: number;\n}\n```\n\n### `tracker.destroy()`\n\n```ts\ntracker.destroy();\n```\n\n## 默认请求路径\n\nSDK 会基于 `baseUrl` 加上 API 契约前缀 `/litetrack/${API_VERSION}`（由 `src/core/version.ts` 显式声明，当前 `v1`，与 SDK 大版本号无关）拼出以下接口：\n\n- 页面访问上报：`${baseUrl}/litetrack/v1/track`\n- 阅读深度上报：`${baseUrl}/litetrack/v1/track/read-progress`\n- 公开统计查询：`${baseUrl}/litetrack/v1/track/stats`\n\n所有请求都会带 `X-LiteTrack-SDK: <版本号>` 请求头，便于后端统计各 SDK 版本使用情况。\n\n## 错误处理\n\n- `page()` / `read()` / 自动上报属于 fire-and-forget，不会向外抛异常\n- 这些异常会进入 `onError`\n- `tracker.stats.site()` / `tracker.stats.page()` 失败时会 reject，同时也会触发 `onError`\n\n## 身份策略\n\n- 默认优先使用浏览器 `localStorage` / `sessionStorage`\n- 如果存储不可用，会自动退化到内存身份，不会让阅读进度直接失效\n\n## 构建与检查\n\n```bash\ncd apps/sdk\n\npnpm build\npnpm type-check\npnpm lint\npnpm test\n```\n\n## 许可证\n\nMIT\n","readmeFilename":"README.md","homepage":"https://github.com/bosens-China/LiteTrack/tree/master/apps/sdk#readme","repository":{"type":"git","url":"git+https://github.com/bosens-China/LiteTrack.git","directory":"apps/sdk"},"bugs":{"url":"https://github.com/bosens-China/LiteTrack/issues"}}