@huyooo/analytics 0.2.0

package/README.md

@@ -0,0 +1,86 @@
+# @huyooo/analytics
+
+ONES 数据中心配套的前端采集 SDK，用于上报 **页面 PV/UV** 与 **Web Vitals 性能指标**。
+
+框架无关，适用于 Vue / React / 原生 SPA。
+
+## 安装
+
+```bash
+npm install @huyooo/analytics
+```
+
+## 快速开始
+
+```typescript
+import { createAnalyticsClient } from '@huyooo/analytics'
+
+const analytics = createAnalyticsClient({
+  appId: 'your-app-id',
+  logPrefixUrl: 'https://log.example.com/logRestfulApi',
+  getToken: () => localStorage.getItem('jwtToken'),
+})
+
+// 监听 pushState / replaceState / popstate / hashchange
+analytics.trackNavigation()
+
+// 挂载完成后采集 Web Vitals（LCP、INP、CLS、FCP、TTFB）
+analytics.startPerformance()
+```
+
+`logPrefixUrl` 会自动推导上报地址：
+
+- PV/UV：`{logPrefixUrl}/analytics/add`
+- 性能：`{logPrefixUrl}/performance/add`
+
+也可显式指定 `analyticsEndpoint` / `performanceEndpoint` 覆盖。
+
+## 配置
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `appId` | `string` | 是 | - | 应用 ID，对应 ONES 数据中心租户 |
+| `logPrefixUrl` | `string` | 否 | - | log-server 前缀，用于推导 endpoint |
+| `analyticsEndpoint` | `string` | 否 | `{logPrefixUrl}/analytics/add` | PV/UV 上报地址 |
+| `performanceEndpoint` | `string` | 否 | `{logPrefixUrl}/performance/add` | 性能上报地址 |
+| `getToken` | `() => string \| null \| undefined` | 否 | - | 返回 JWT，关联登录用户 |
+| `enablePerformance` | `boolean` | 否 | `true` | 是否采集 Web Vitals |
+| `dedupePageView` | `boolean` | 否 | `true` | 同一路径重复 PV 去重 |
+| `debug` | `boolean` | 否 | `false` | 开发调试日志（见下方说明） |
+
+## API
+
+`createAnalyticsClient(config)` 返回：
+
+| 方法 | 说明 |
+|------|------|
+| `trackPageView(options?)` | 手动上报一次 PV，`options.pathname` 可覆盖路径 |
+| `trackNavigation()` | 监听浏览器路由变化并自动上报 PV |
+| `startPerformance()` | 注册 Web Vitals 采集并上报 |
+| `destroy()` | 卸载路由监听，重置内部状态 |
+
+`trackNavigation()` 会 patch `history.pushState` / `history.replaceState`，并监听 `popstate`、`hashchange`；首次调用时立即上报当前页 PV。Vue Router、React Router 等基于 History API 的路由均可直接使用。
+
+## 上报数据
+
+### PV/UV
+
+包含 `appId`、设备信息（UA、屏幕、语言等）、位置信息（pathname、referrer、sessionId 等），以及可选的 `authorization`（来自 `getToken`）。
+
+### 性能
+
+基于 [web-vitals](https://github.com/GoogleChrome/web-vitals)，上报 LCP、INP、CLS、FCP、TTFB 及对应阈值配置。
+
+## 开发与构建
+
+```bash
+npm run dev        # tsdown watch，未压缩，适合本地调试
+npm run build      # 压缩产物（minify + treeshake）
+npm run typecheck
+```
+
+发布产物会移除 `console` 调用，`debug: true` 仅在 `npm run dev` 本地调试时有效。
+
+## 与 @huyooo/ui 的关系
+
+`@huyooo/ui/analytics` 为兼容 re-export，新接入请直接依赖 `@huyooo/analytics`。

package/dist/collectors/pageView.d.ts

@@ -0,0 +1,3 @@
+import type { AnalyticsConfig, PageViewPayload } from '../types';
+/** 构建 PV 上报 payload */
+export declare function buildPageViewPayload(config: AnalyticsConfig, pathname?: string): PageViewPayload;

package/dist/collectors/performance.d.ts

@@ -0,0 +1,6 @@
+import type { Metric } from 'web-vitals';
+import type { AnalyticsConfig, PerformancePayload } from '../types';
+/** 构建性能上报 payload */
+export declare function buildPerformancePayload(config: AnalyticsConfig, metric: Metric): PerformancePayload;
+/** 注册 Web Vitals 采集（全局只应调用一次） */
+export declare function registerPerformanceCollectors(config: AnalyticsConfig, onMetric: (payload: PerformancePayload) => void): void;

package/dist/context/browser.d.ts

@@ -0,0 +1,2 @@
+/** 是否在浏览器环境 */
+export declare function isBrowser(): boolean;

package/dist/context/device.d.ts

@@ -0,0 +1,26 @@
+export interface AnalyticsDeviceInfo {
+    ua: string;
+    browser: UAParser.IBrowser;
+    cpu: UAParser.ICPU;
+    device: UAParser.IDevice;
+    engine: UAParser.IEngine;
+    os: UAParser.IOS;
+    screenResolution: string;
+    platform: string;
+    language: string;
+}
+export interface AnalyticsLocationInfo {
+    host: string;
+    hostname: string;
+    href: string;
+    origin: string;
+    pathname: string;
+    port: string;
+    protocol: string;
+    referrer: string;
+    sessionId: string;
+}
+/** 获取设备信息 */
+export declare function getDevice(): AnalyticsDeviceInfo;
+/** 获取页面位置信息 */
+export declare function getLocation(pathname?: string): AnalyticsLocationInfo;

package/dist/context/session.d.ts

@@ -0,0 +1,2 @@
+/** 获取或创建会话 ID */
+export declare function getSessionId(): string;

package/dist/createAnalyticsClient.d.ts

@@ -0,0 +1,3 @@
+import type { AnalyticsClient, AnalyticsConfig } from './types';
+/** 创建数据采集客户端 */
+export declare function createAnalyticsClient(config: AnalyticsConfig): AnalyticsClient;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createAnalyticsClient } from './createAnalyticsClient';
+export { resolveEndpoints } from './resolveEndpoints';
+export type { AnalyticsClient, AnalyticsConfig, PageViewPayload, PerformancePayload, ResolvedAnalyticsEndpoints, } from './types';

package/dist/index.js

@@ -0,0 +1 @@
+import{CLSThresholds as e,FCPThresholds as t,INPThresholds as n,LCPThresholds as r,TTFBThresholds as i,onCLS as a,onFCP as o,onINP as s,onLCP as c,onTTFB as l}from"web-vitals";import{UAParser as u}from"ua-parser-js";import{v4 as d}from"uuid";function f(){return typeof window<`u`&&typeof document<`u`}const p=`_analytics_session_id`;function m(){if(!f())return``;let e=sessionStorage.getItem(p);return e||(e=d(),sessionStorage.setItem(p,e)),e}function h(){return{ua:``,browser:{name:void 0,version:void 0,major:void 0},cpu:{architecture:void 0},device:{model:void 0,type:void 0,vendor:void 0},engine:{name:void 0,version:void 0},os:{name:void 0,version:void 0},screenResolution:``,platform:`Unknown`,language:`Unknown`}}function g(){return{host:``,hostname:``,href:``,origin:``,pathname:``,port:``,protocol:``,referrer:`direct`,sessionId:``}}function _(){return f()?{...new u().getResult(),screenResolution:`${window.screen.width}x${window.screen.height}`,platform:/Android|iOS|iPad|iPhone/i.test(navigator.userAgent)?`Mobile App`:`Web`,language:navigator.language||`Unknown`}:h()}function v(e){if(!f())return g();let t=e??location.pathname;return{host:location.host,hostname:location.hostname,href:`${location.origin}${t}${location.search}${location.hash}`,origin:location.origin,pathname:t,port:location.port,protocol:location.protocol,referrer:document.referrer||`direct`,sessionId:m()}}function y(e){let t=e.getToken?.();return t?t.startsWith(`Bearer `)?t:`Bearer ${t}`:``}function b(a,o){return{appId:a.appId,authorization:y(a),device:_(),location:v(),metric:o,reports:{CLSThresholds:e,FCPThresholds:t,INPThresholds:n,LCPThresholds:r,TTFBThresholds:i}}}function x(e,t){let n=n=>{t(b(e,n))};a(n),o(n),s(n),c(n),l(n)}function S(e){let t=e.getToken?.();if(t)return t.startsWith(`Bearer `)?t:`Bearer ${t}`}function C(e,t){let n={appId:e.appId,device:_(),location:v(t)},r=S(e);return r&&(n.authorization=r),n}function w(e){if(!f())return()=>{};e();let t=history.pushState.bind(history),n=history.replaceState.bind(history);function r(){e()}return history.pushState=(...e)=>{t(...e),r()},history.replaceState=(...e)=>{n(...e),r()},window.addEventListener(`popstate`,r),window.addEventListener(`hashchange`,r),()=>{history.pushState=t,history.replaceState=n,window.removeEventListener(`popstate`,r),window.removeEventListener(`hashchange`,r)}}function T(e){let t=e.logPrefixUrl?.replace(/\/$/,``)??``;return{analytics:e.analyticsEndpoint??`${t}/analytics/add`,performance:e.performanceEndpoint??`${t}/performance/add`}}function E(e,t){let n=JSON.stringify(t);typeof navigator<`u`&&typeof navigator.sendBeacon==`function`&&navigator.sendBeacon(e,new Blob([n],{type:`application/json`}))||D(e,n)}function D(e,t){fetch(e,{method:`POST`,headers:{"Content-Type":`application/json`},body:t,keepalive:!0}).catch(e=>{})}function O(e){let t=T(e),n=!1,r=``,i=null;function a(t,n){e.debug}function o(n){if(!f())return;let i=C(e,n?.pathname),o=i.location.pathname;e.dedupePageView!==!1&&o===r||(r=o,a(`trackPageView`,i),E(t.analytics,i))}function s(){i||(i=w(o),a(`trackNavigation`))}function c(){!f()||n||e.enablePerformance===!1||(n=!0,a(`startPerformance`),x(e,e=>{a(`performance metric`,e.metric),E(t.performance,e)}))}function l(){i?.(),i=null,n=!1,r=``}return{trackPageView:o,trackNavigation:s,startPerformance:c,destroy:l}}export{O as createAnalyticsClient,T as resolveEndpoints};

package/dist/navigation/attachHistoryNavigation.d.ts

@@ -0,0 +1,2 @@
+/** 监听 History / hash 变化，返回卸载函数 */
+export declare function attachHistoryNavigation(trackPageView: () => void): () => void;

package/dist/resolveEndpoints.d.ts

@@ -0,0 +1,3 @@
+import type { AnalyticsConfig, ResolvedAnalyticsEndpoints } from './types';
+/** 解析上报 endpoint */
+export declare function resolveEndpoints(config: AnalyticsConfig): ResolvedAnalyticsEndpoints;

package/dist/transport/sendPayload.d.ts

@@ -0,0 +1,2 @@
+/** 发送 JSON 数据，优先 sendBeacon */
+export declare function sendPayload(url: string, data: unknown): void;

package/dist/types.d.ts

@@ -0,0 +1,49 @@
+import type { Metric } from 'web-vitals';
+import type { AnalyticsDeviceInfo, AnalyticsLocationInfo } from './context/device';
+export interface AnalyticsConfig {
+    appId: string;
+    /** 完整上报地址；未传时由 logPrefixUrl 推导 */
+    analyticsEndpoint?: string;
+    performanceEndpoint?: string;
+    logPrefixUrl?: string;
+    /** 返回 JWT，用于关联登录用户 */
+    getToken?: () => string | null | undefined;
+    /** 是否采集 Web Vitals，默认 true */
+    enablePerformance?: boolean;
+    /** 同一路径重复 PV 去重，默认 true */
+    dedupePageView?: boolean;
+    debug?: boolean;
+}
+export interface AnalyticsClient {
+    trackPageView: (options?: {
+        pathname?: string;
+    }) => void;
+    /** 监听 History / hash 路由变化并上报 PV（跨框架） */
+    trackNavigation: () => void;
+    startPerformance: () => void;
+    destroy: () => void;
+}
+export interface ResolvedAnalyticsEndpoints {
+    analytics: string;
+    performance: string;
+}
+export interface PageViewPayload {
+    appId: string;
+    device: AnalyticsDeviceInfo;
+    location: AnalyticsLocationInfo;
+    authorization?: string;
+}
+export interface PerformancePayload {
+    appId: string;
+    authorization: string;
+    device: AnalyticsDeviceInfo;
+    location: AnalyticsLocationInfo;
+    metric: Metric;
+    reports: {
+        CLSThresholds: readonly number[];
+        FCPThresholds: readonly number[];
+        INPThresholds: readonly number[];
+        LCPThresholds: readonly number[];
+        TTFBThresholds: readonly number[];
+    };
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@huyooo/analytics",
+  "version": "0.2.0",
+  "description": "ONES 数据中心配套的前端采集 SDK（流量 PV/UV + Web Vitals 性能）",
+  "private": false,
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://cnb.cool/huyooo/infra/analytics.git"
+  },
+  "scripts": {
+    "dev": "tsdown --watch",
+    "build": "npm run clean && npm run build:js && npm run build:types",
+    "build:js": "tsdown",
+    "build:types": "tsc -b tsconfig.json --emitDeclarationOnly",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "typecheck": "tsc --noEmit",
+    "pub": "npm version patch --force && npm publish --access public",
+    "release": "bumpp && npm publish --access public",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "ua-parser-js": "^1.0.38",
+    "uuid": "^11.1.0",
+    "web-vitals": "^4.2.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.1",
+    "@types/ua-parser-js": "^0.7.39",
+    "bumpp": "^10.2.0",
+    "tsdown": "^0.21.0",
+    "typescript": "^5.5.3"
+  }
+}