@lark-apaas/observable-web-lite

轻量 PV/UV 上报 SDK，零外部依赖，产物 ~5KB。

适用于只需要 PV/UV 统计、不需要 Logs/Traces/Metrics 全量能力的项目。与 @lark-apaas/observable-web 后端完全兼容（相同 metric name + payload 格式），收集端点无需改动。

安装

yarn add @lark-apaas/observable-web-lite

快速开始

import { pvTracker } from '@lark-apaas/observable-web-lite';

const appId = window.appId || '';
pvTracker.start({
  collectorUrl: `/app/${appId}/__runtime__/api/v1/observability/metrics/collect`,
});

一行代码即可启用 PV/UV 自动上报，SDK 会自动监听：

• 页面首次加载（load）
• 浏览器前进/后退（popstate）
• SPA 路由跳转（pushState / replaceState）
• 页面切后台/关闭时立即 flush（visibilitychange / pagehide）

API

pvTracker.start(config)

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | collectorUrl | string | 是 | Metric 收集端点 URL | | headers | Record<string, string> | 否 | 附加 HTTP headers | | flushIntervalMs | number | 否 | 批量发送间隔，默认 10000ms |

pvTracker.shutdown()

停止上报并立即 flush 剩余数据。

完整示例

在 React 应用入口使用

// client/src/index.tsx
import { pvTracker } from '@lark-apaas/observable-web-lite';

const appId = window.appId || '';
pvTracker.start({
  collectorUrl: `/app/${appId}/__runtime__/api/v1/observability/metrics/collect`,
  flushIntervalMs: 5000, // 5 秒 flush 一次
});

ReactDOM.createRoot(document.getElementById('root')!).render(<App />);

自定义实例（多实例场景）

import { PvTracker } from '@lark-apaas/observable-web-lite';

const tracker = new PvTracker();
const appId = window.appId || '';
tracker.start({
  collectorUrl: `/app/${appId}/__runtime__/api/v1/observability/metrics/collect`,
});

// 页面卸载时
tracker.shutdown();

与 observable-web 的对比

| | observable-web | observable-web-lite | |---|---|---| | 产物大小 | ~50KB | ~5KB | | 外部依赖 | 9 个（OTel + zone.js） | 0 | | PV/UV 上报 | ✅ | ✅ | | 日志（Logs） | ✅ | ❌ | | 指标（Metrics） | ✅ | ❌ | | 链路追踪（Traces） | ✅ | ❌ | | ESM 支持 | ❌ | ✅ | | tree-shake | ❌ | ✅ |

注意事项

• 与 observable-web 不要同时启用 PV 上报，否则会重复计数
• 如果项目后续需要 Logs/Traces 能力，切换回 observable-web 即可，PV 数据无缝衔接（metric name 相同）
• SDK 默认读取 window.appId / window.tenantId / window.userId 作为上报属性，这些由服务端 ViewContextPlugin 注入