ux-analytics-sdk

ux-analytics-sdk

版本

// beta
npm run version:beta
// patch
npm run version:patch
// minor
npm run version:minor
// major
npm run version:major

打包

npm run lib

发布

// 正式版本
npm run pub
// 测试版本
npm run pub:beta

使用指南

以下指南基于源码中的完整 SDK 能力。当前打包入口为 packages/main.ts，导出 AnalyticsSDK 类、createSDK()、getSDK() 函数。

安装

npm i ux-analytics-sdk

快速开始（推荐完整 API）

import { AnalyticsSDK } from 'ux-analytics-sdk';

const sdk = new AnalyticsSDK({
	endpoint: 'https://api.example.com/api/v1',
	appSecret: 'your-app-secret', // 服务端鉴权密钥，作为请求头 uxdc-app-secret 发送
	token: 'your-api-token', // API Token（可选），作为请求头发送
	tokenHeaderName: 'Authorization', // Token 请求头名称，默认 'Authorization'
	platform: 'web', // 运行平台：web、ios、android、mini_program、other
	autoTrack: {
		pageView: true, // 自动上报首次 PV
		click: { enable: true, selector: '*', exclude: ['.no-track'] },
		error: true,
		performance: false,
	},
	sampling: { globalRate: 1.0, eventRates: { pv: 1.0, click: 1.0, custom: 1.0 } },
	batching: { maxBatchSize: 20, maxBatchBytes: 1024 * 100, flushIntervalMs: 5000, flushOnHidden: true, flushOnUnload: true },
	storage: { useIndexedDB: false },
	debug: true,
});

await sdk.init();

// 手动上报
sdk.trackPageView();
sdk.trackClick(document.querySelector('button')!);
sdk.track({ event_name: 'signup', event_category: 'user', event_label: 'cta', event_value: 1 });

// 需要时可主动刷新或销毁
await sdk.flush();
await sdk.destroy();

事件类型与路由

• pv: 页面浏览事件，发送到 /events/page-view（POST）。
• page-leave: 页面离开事件（记录停留时间），发送到 /events/page-leave。
• click: 点击事件，发送到 /events/click。点击事件字段包括：
  • element_selector: 元素选择器（优先级：#id > .class1.class2 > 标签名）
    • element_name: 优先 data-ux-name，否则为标签名（小写）
  • element_content: 元素文本内容（去除前后空格和换行符，最多 200 字符）
    • 采集规则：非图片元素（非 IMG）且内容为空时不采集；图片元素始终采集
• custom: 自定义事件（错误、性能也以自定义事件形式上报），发送到 /events/custom。
• sessions: 会话记录，发送到 /sessions。会话开始时自动上报会话信息（包括 platform、device_id、start_time 等）。

服务端基础地址通过配置项 endpoint 指定，例如 https://api.example.com/api/v1。SDK 会在发送时拼接相应路径。

自动采集（autoTrack）

• pageView: 首次加载时自动上报 PV；页面隐藏/卸载时上报 page-leave。
• click.enable: 开启点击采集；支持 selector 约束范围与 exclude 排除选择器（命中排除则不采集）。
• error: 监听 error 与 unhandledrejection 事件并生成错误类自定义事件。
• performance: 使用 PerformanceObserver 采集导航、资源、绘制、LCP 等指标为自定义事件。

SPA 路由追踪（Vue Router）

SDK 提供 trackVueRouter(to, from, config?) 用于记录路由切换的上一页停留与新页 PV。

// 在路由全局守卫中调用
router.afterEach((to, from) => {
	sdk.trackVueRouter(to, from, {
		resoloveFromPath: (from) => from.fullPath,
		resoloveFromTitle: (from) => from.meta?.title || String(from.name || ''),
		resoloveToPath: (to) => to.fullPath,
		resoloveToTitle: (to) => to.meta?.title || String(to.name || ''),
		// 可选：去抖间隔（默认 300ms）
		debounceMs: 300,
	})
})

采样（sampling）

• globalRate: 全局采样率（0~1）。
• eventRates: 针对 pv、click、custom 的事件级采样率，优先于全局。

批量与刷新（batching）

• maxBatchSize: 每次刷新最多发送条数。
• maxBatchBytes: 每批最大字节（JSON 估算），超限自动拆分。
• flushIntervalMs: 定时刷新间隔（毫秒）。
• flushOnHidden/flushOnUnload: 页面隐藏或卸载时触发发送（优先 sendBeacon）。

队列持久化（storage）

• useIndexedDB: 优先使用 IndexedDB 持久化队列，不可用时回退到 localStorage。

插件机制

SDK 支持在事件入队、批量发送前后进行扩展：

const headersPlugin = {
	name: 'headers',
	setup(cfg) {
		// 可在此读取 cfg，进行环境初始化。
	},
	beforeQueue(event) {
		// 修改或过滤事件
		return event;
	},
	beforeSend(batch) {
		// 批量发送前处理事件数组
		return batch;
	},
	afterSend(results) {
		// 处理发送结果
	},
};

sdk.use(headersPlugin);

API 一览

• new AnalyticsSDK(config): 创建实例，支持上文所有配置（包括 platform、token、appSecret、spa、minStayDuration 等）。
• init(): 初始化用户身份与会话，启用自动采集与定时刷新。会话开始时自动上报会话记录到 /sessions。
• use(plugin): 注册插件，支持生命周期钩子。
• track(event): 上报自定义事件（event_name、event_category、event_label、event_value），支持 BuildCustomEventExtra 类型。
• trackPageView(extra?: BuildPvEventExtra): 上报页面浏览事件，支持可选扩展字段。
• trackPageLeave(extra?: BuildPageLeaveEventExtra): 上报页面离开事件，记录停留时间。
• trackClick(element, extra?: BuildClickEventExtra): 上报点击事件，支持可选扩展字段。
• trackVueRouter(to, from, config?): 在路由切换后调用，自动上报上一页的 page-leave 与新页面的 PV；config.debounceMs 可配置去抖间隔（默认 300ms）。
• flush(): 立即发送队列中的事件（考虑批量与字节限制）。
• destroy(): 停止自动采集、清理定时器并发送剩余事件，结束会话。
• createSDK(cfg) / getSDK(): 全局 SDK 实例的创建与获取。

服务端兼容与注意事项

• 传输策略：

  • 页面隐藏时优先使用 Image 像素请求（GET，事件数据转为 query params）。
  • 正常情况下优先使用 fetch（POST）；失败则回退到 XMLHttpRequest。
  • 失败重试采用指数退避，最多 4 次，仅对 429 与 5xx 响应重试。
  • 所有方法失败后最终尝试 Image 像素兜底。

• 请求头：

  • token: 通过 tokenHeaderName 配置的请求头发送（默认 Authorization），fetch/XHR 方式支持。
  • appSecret: 通过 uxdc-app-secret 请求头发送，fetch/XHR 方式支持；Image 像素方式会附加到 query params。
  • 注意：Image 像素请求无法设置自定义请求头，因此 token 信息不会包含在该方式中，仅 appSecret 会附加到 URL。

• 端点路由：基于事件类型自动拼接到 endpoint（pv → /events/page-view，page-leave → /events/page-leave，click → /events/click，custom → /events/custom，session → /sessions）。

• 会话管理：SDK 自动管理用户身份（user_uuid）、设备 ID（device_id）、会话 ID（session_id）；会话超时 30 分钟或跨日自动重启。会话开始时上报会话记录到 /sessions。

示例项目

• 示例参见 example/vite。