🌐 **[中文文档](./README.zh-CN.md) · [English](./README.md)**
# 📦 Web Collection SDK 指标说明
> 开箱即用的浏览器端 SDK：错误、性能、回放、链路与行为采集。
[](https://www.npmjs.com/package/@web-collection/sdk) [](https://www.npmjs.com/package/@web-collection/sdk) [](https://github.com/programmerguohuajing/web-collection/blob/main/packages/sdk/LICENSE) [](https://github.com/programmerguohuajing/web-collection/blob/main/packages/sdk/index.d.ts)
**Web Collection SDK** 是为 [Web Collection](https://github.com/programmerguohuajing/web-collection) 控制台提供数据的浏览器端采集器，以轻量、框架无关的内核采集错误、性能、会话回放、分布式链路与行为数据。
## 📑 目录
- [🚀 接入](#接入)
- [🔒 隐私与数据最小化](#隐私与数据最小化)
- [🔗 分布式链路追踪与调用拓扑](#分布式链路追踪与调用拓扑)
- [🎯 手动埋点](#手动埋点)
- [📊 行为指标](#行为指标)
- [⚡ 性能指标](#性能指标)
- [🌐 请求指标](#请求指标)
- [🐛 错误指标](#错误指标)
- [💰 采样与成本控制](#采样与成本控制)
- [🎬 会话回放](#会话回放)
- [📋 通用字段](#通用字段)
- [📡 队列、传输与上报](#队列传输与上报)
- [📱 小程序与 App 接入](#小程序与-app-接入)
## 🔌 接入
```js
import { createEys } from '@web-collection/sdk'
const eys = createEys({
endpoint: 'https://your-domain.com/api/collect',
appId: 'mall-web',
release: '1.0.0',
userId: '10001',
userName: '张三',
userPhone: '13800000000'
})
```
登录后补用户信息：
```js
eys.setUser({ id: '10001', name: '张三', phone: '13800000000' })
```
业务首屏数据渲染完成后主动标记“页面数据就绪”：
```js
eys.markPageReady()
```
关闭模块：
```js
createEys({
behavior: false,
requests: false,
exposure: false,
replay: false
})
```
开启 `console: true` 后，会采集 `console.log/info/warn/error`，并保留最近 20 条控制台面包屑（单条最多 500 字符），用于检索及还原报错上下文。该能力默认关闭，避免意外采集业务日志中的敏感数据；可用 `consoleLevels` 限定级别。
同时可主动记录结构化日志：
```js
eys.log('info', '订单提交', { orderId: 'SO10001' })
```
请求链路默认开启，同源 Fetch/XHR 会携带标准 `traceparent`。跨域服务必须显式加入可信列表：
```js
createEys({
collectKey: 'eys_xxx',
traceOrigins: ['https://api.example.com']
})
```
TypeScript 项目可直接导入类型：
```ts
import { createEys, type EysClient, type EysOptions } from '@web-collection/sdk'
const options: EysOptions = {
endpoint: 'https://your-domain.com/api/collect',
appId: 'mall-web',
release: '1.0.0'
}
const eys: EysClient = createEys(options)
eys.track('submit_order', { orderId: 'SO202607100001' })
```
### Script 接入（无构建步骤）
无需打包工具时，直接通过 `
```
`replay: true` 时 rrweb 不会打入核心包，IIFE 场景需由外部环境提供 `window.rrweb`（或用 `replayLibUrl` 指向自托管的 rrweb 脚本），详见[会话回放](#会话回放)。
### Vue 接入
```js
import { createApp } from 'vue'
import WebCollection from '@web-collection/sdk'
import App from './App.vue'
createApp(App).use(WebCollection, {
endpoint: 'https://your-domain.com/api/collect',
appId: 'web',
release: '1.0.0'
}).mount('#app')
```
- `WebCollection` 是 SDK 默认导出，作为 Vue 插件通过 `app.use()` 安装后自动完成初始化。
- 插件劫持 `app.config.errorHandler`，组件渲染期错误经 `eys.error` 自动上报（携带 `source: 'vue'`、组件名与渲染信息 `info`），无需手动 try/catch。
- 实例挂载到 `app.config.globalProperties.$eys`，组件内通过 `this.$eys` 调用埋点、日志等方法：
```js
// 选项式 API
this.$eys.track('checkout_clicked', { plan: 'pro' })
```
Vue Router 的页面切换与路由变更会被自动采集——SDK 已劫持 `history.pushState` / `replaceState` 与 `popstate` / `hashchange`，无需额外接入。要求 Vue 3.x。
### React 接入
```jsx
import React from 'react'
import { createRoot } from 'react-dom/client'
import { WebCollectionProvider, ErrorBoundary, useWebCollection } from '@web-collection/sdk/react'
import App from './App'
createRoot(document.getElementById('root')).render(
页面出错了}>
)
```
- `WebCollectionProvider` 在应用根挂载一次并完成 SDK 初始化（在 `useEffect` 中执行，仅客户端，因此 Next.js 等 SSR 场景天然安全），通过 React Context 下发实例。
- `ErrorBoundary` 捕获子树渲染错误并通过 `eys.error` 自动上报。React 没有 Vue 那种 `app.config.errorHandler` 全局钩子，渲染期错误必须由 Error Boundary 捕获。可用 `fallback` 指定兜底 UI，或用 `eys` 传入外部创建的实例。
- `useWebCollection()` 从 Context 获取 SDK 实例（初始化完成前返回 `null`，建议在事件回调 / effect 中使用，而非首次渲染期依赖）。
```jsx
function CheckoutButton() {
const eys = useWebCollection()
return
}
```
React Router 的页面切换与路由变更会被自动采集——SDK 已劫持 `history.pushState` / `replaceState` 与 `popstate` / `hashchange`，无需额外接入。要求 React 16.8+。
采集治理与上下文：
```js
const eys = createEys({
environment: 'production',
consent: 'granted',
categorySampleRates: { behavior: 0.5, replay: 0.1 },
privacy: { redactKeys: ['orderToken'], requestAllowlist: ['https://api.example.com'] },
beforeSend(event) {
return event.context?.debug ? false : event
}
})
eys.setContext({ module: 'checkout' })
eys.addBreadcrumb('checkout_started', { source: 'cart' })
eys.setConsent('denied')
eys.setEnabled(false)
```
`consent` 默认是 `granted`，拒绝后事件不会进入队列或发起请求。内置脱敏先于 `beforeSend` 执行，请勿在回调中恢复敏感数据。设备环境指纹默认开启（`environmentInfo: true`）；运行时版本信息默认关闭（`runtimeInfo: false`）——开启后会在上下文中附加运行时 / SDK 版本。
## 🔒 隐私与数据最小化
SDK 默认尽量少的采集敏感数据。统一的脱敏引擎（`privacy.mode`）在每条事件**入队前**以及 `beforeSend` **之后**各执行一次，因此即便自定义钩子重新引入敏感数据，也不会被发出。
| 档位 | 行为 | 适用 |
| --- | --- | --- |
| `off` | 不做任何隐私保护（仅保留既有 `redactKeys` 字段脱敏） | 业务显式关闭保护、内网可信环境 |
| `balanced`（**默认**） | 字段键脱敏 + 值级 PII 文本脱敏 + 手机号不可逆 hash + URL 敏感参数剥离 + 头丢弃 + body 清洗 | 生产环境默认最小化采集 |
| `strict` | 在 balanced 基础上进一步：URL 丢弃整个 query、下拉框仅采索引与数量 | 强合规场景 |
`balanced` 默认自动完成：
- **字段键脱敏**：命中 `password`/`token`/`secret`/`authorization`/`cookie`/`apikey` 等敏感 key 整体替换为 `[REDACTED]`。
- **值级 PII 文本脱敏**：对字符串叶子值精准匹配并脱敏邮箱、中国大陆手机号、身份证（18 位）、银行卡（16–19 位）、JWT。
- **用户手机号不可逆 hash**：`balanced`/`strict` 下 `userPhone` 经 FNV-1a + 长度信息的 `h_*` 代称，服务端无法还原。
- **请求 / 响应头丢弃**：默认移除 `Authorization`/`Cookie`/`Set-Cookie`/`Proxy-Authorization`，可经 `dropHeaders` 追加。
- **URL query 剥离**：仅剥 `token`/`code`/`phone`/`idcard` 等敏感参数；`strict` 丢弃整个 query。
- **请求 / 响应 body 清洗**：JSON body 递归字段脱敏、文本 body 做 PII 脱敏；支持自定义 `requestResponseSanitizer` 钩子。
```js
WebCollection.createEys({
appId: 'web-app',
privacy: {
mode: 'balanced', // 默认即 balanced，可显式声明
redactKeys: ['mySecret'], // 在默认敏感字段基础上追加
dropHeaders: ['x-api-secret'],
textRedaction: true, // 默认开启
consentCategories: { replay: true }, // 显式授权可覆盖 GPC/DNT
requestResponseSanitizer: (pair) => ({ ...pair, requestBody: 'REDACTED' })
}
})
```
**同意分类与 GPC / DNT**：`consent` 默认是 `granted`，拒绝后仅保留 `essential`。浏览器发出 **GPC**（`navigator.globalPrivacyControl === true`）或 **DNT**（`navigator.doNotTrack` 为 `1/yes/true`）信号时，未被显式授权的 `analytics`/`replay`/`diagnostics` 降级为拒绝。自查接口：`getPrivacyMode()`、`getConsentCategories()`。
回放遮罩仍沿用 DOM 中的 `.eys-block`（不录制）与 `.eys-ignore`（输入框不录制）。
## 🔗 分布式链路追踪与调用拓扑
SDK 可以把页面性能、Fetch 和 XHR 事件关联为一棵分布式调用树。拓扑图不是在 SDK 内绘制的：SDK 负责上报 `traceId`、`spanId` 和 `parentSpanId`，监控平台再把相同 `traceId` 的节点聚合起来，并按父子 ID 建立连线。
### 快速接入
```js
const eys = createEys({
endpoint: 'https://monitor.example.com/api/collect',
appId: 'checkout-web',
release: '1.2.0',
// 采集 Fetch/XHR 的耗时和状态。
requests: true,
// 为请求指标添加链路 ID，并向可信请求注入 traceparent。
tracing: true,
// 创建页面根 Span 和具有父子关系的请求 Span。
distributedTracing: true,
// 同源请求默认可信；跨域 API 必须写入精确的协议、域名和端口。
traceOrigins: [
'https://api.example.com',
'https://payment.example.com'
],
// 以标准 W3C `baggage` 请求头传播的静态、非敏感业务上下文。
// 不要放入密码、Token、Cookie、手机号或其他敏感信息。
baggage: {
tenant: 'shop',
region: 'cn-east'
},
// SDK/会话的全局采样率；高流量生产环境应降低该值。
sampleRate: 0.2
})
```
所有链路开关默认均为开启。要形成完整的自动请求拓扑，需要同时保持 `requests`、`tracing` 和 `distributedTracing` 为开启状态。
| 配置项 | 默认值 | 作用 |
| --- | --- | --- |
| `requests` | `true` | 采集 Fetch/XHR 的耗时、方法、状态和失败信息；关闭后不再自动生成请求节点。 |
| `tracing` | `true` | 为请求指标附加链路标识，并向可信请求注入 `traceparent`。 |
| `distributedTracing` | `true` | 创建页面根 Span 和层级化子 Span，使平台能够根据 `parentSpanId` 还原父子关系。 |
| `traceOrigins` | `[]` | 允许接收链路请求头的跨域 Origin，支持精确字符串、`RegExp` 或 `(origin) => boolean` 匹配函数；同源请求始终允许。 |
| `baggage` | `{}` | 以标准 W3C 单一 `baggage` 请求头传播的静态、非敏感业务上下文。 |
| `sampleRate` | `1` | `0` 到 `1` 的全局会话采样率；当前会话未命中采样时返回空实现客户端。 |
| `categorySampleRates` | `{}` | 可选的分类采样率覆盖，在适用场景下也参与 Trace 采样标记。 |
| `spanExport` | `false` | 开启后，页面根 / 自动请求 / 自定义 Span 经 Processor/Exporter 批量写入 `/api/spans`（0.2.0-beta 起可配合采样默认开启）。 |
### 拓扑是如何形成的
使用上述配置时，浏览器侧会产生类似以下层级：
```text
page（根 Span）
├─ navigation 页面性能
├─ fetch https://api.example.com/orders
│ └─ order-api 服务端 Span
│ └─ 数据库或下游服务 Span
└─ xhr https://payment.example.com/pay
└─ payment-api 服务端 Span
```
各链路字段的职责不同：
| 字段 | 含义 |
| --- | --- |
| `traceId` | 同一次端到端调用中的所有节点共用。 |
| `spanId` | 标识一次独立操作，例如页面、某个 Fetch/XHR 请求或服务端操作。 |
| `parentSpanId` | 指向调用方的 `spanId`，用于生成父子连线。 |
| `traceFlags` | 通过 W3C `traceparent` 请求头携带采样决策。 |
SDK 会自动创建页面根上下文和请求子 Span。要让调用树从浏览器继续连接到后端，每个服务都必须：
1. 读取传入的 W3C `traceparent` 请求头。
2. 保留传入的 `traceId`。
3. 创建新的服务端 `spanId`，并把传入的 `spanId` 作为 `parentSpanId`。
4. 调用下游服务时继续传递更新后的 `traceparent`。
5. 把服务端 Span 上报到同一套监控后端。
如果某个服务重新生成 `traceId`、丢失 `parentSpanId`，或者没有上报自己的 Span，平台只能显示浏览器节点或一段断开的调用分支。
### 跨域与 CORS 要求
只有目标请求与当前页面同源，或者目标的精确 Origin 已加入 `traceOrigins` 时，SDK 才会注入链路请求头。不要配置通配或不可信域名：链路和 baggage 请求头可能暴露内部关联信息。
跨域 API 必须在 CORS 预检中允许相关请求头。服务端或网关至少需要允许 `traceparent` 以及 `baggage` 请求头。如果服务端返回 `traceparent` 或 `traceresponse`，并且浏览器需要读取，还应暴露这些响应头。
```http
Access-Control-Allow-Headers: Content-Type, Authorization, traceparent, baggage
Access-Control-Expose-Headers: traceparent, traceresponse
```
配置 `traceOrigins` 不会绕过 `privacy.requestAllowlist`。设置了请求白名单时，目标 URL 必须同时满足隐私白名单和 Trace Origin 规则，SDK 才会注入链路请求头。
### 查看与排查分布式调用树
在监控平台打开 Trace 详情，然后切换到 **分布式调用树** 标签。有效且非空的拓扑要求已上报节点拥有相同的 `traceId`，并包含合法的 `spanId`/`parentSpanId` 关系。
如果页面只有顶部统计信息却没有拓扑，请依次检查：
1. `requests`、`tracing` 和 `distributedTracing` 没有被设置为 `false`。
2. `sampleRate` 大于 `0`，且当前会话命中了采样。
3. 当前请求不是 SDK 自己的采集接口。
4. 配置 `privacy.requestAllowlist` 后，白名单包含目标请求 URL。
5. 跨域地址与 `traceOrigins` 精确匹配，包括协议和端口。
6. 浏览器开发者工具中存在格式为 `00---` 的合法 `traceparent` 请求头。
7. CORS 已允许链路和 baggage 请求头。
8. 后端服务保留传入的 `traceId`、生成新的 `spanId`、记录 `parentSpanId`，并上报服务端 Span。
9. 监控平台筛选的是正确的应用、发布版本和时间范围。
生产环境建议从较低的 `sampleRate` 开始，根据采集量、存储和查询预算逐步调整。`baggage` 会随每个链路请求发送，应保持精简且不得包含敏感信息。
## 🎯 手动埋点
```js
eys.track('submit_order', {
orderId: 'SO202607100001',
amount: 99
})
```
入库字段：
| 字段 | 说明 |
| --- | --- |
| `type` | `track` |
| `name` | 自定义事件名 |
| `props` | 自定义业务参数 |
## 📊 行为指标
默认由 `behavior: true` 开启。
| 指标 | 触发时机 | 主要 props |
| --- | --- | --- |
| `pv` | SDK 初始化后页面访问 | `referrer` |
| `page_leave` | 页面隐藏时 | `stayTime` |
| `click` | 点击 `data-track/button/a/input/textarea/select/[role=button]` | `elementLabel`、`elementType`、`elementId`、`elementText`、`elementHref` |
| `scroll` | 页面滚动停止约 500ms 后 | `depth`、`maxDepth` |
| `pushState` | SPA 调用 `history.pushState` | `from`、`to` |
| `replaceState` | SPA 调用 `history.replaceState` | `from`、`to` |
| `popstate` | 浏览器前进后退 | `from`、`to` |
| `hashchange` | hash 路由变化 | `from`、`to` |
| `exposure` | 元素进入视口 50% 且停留约 1 秒 | 元素 `tag/id/className/text/data-track-*` |
以下可选行为默认关闭：
```js
createEys({
formTracking: true, // 表单提交 / 输入框聚焦失焦
rageClick: true, // 快速重复点击
deadClick: true, // 无效点击（需元素加 data-track-dead-click）
interactionTracking: true, // 通用交互事件
selectTracking: true, //