diff --git a/README.md b/README.md index 406b727d323d976953b79e4ec0cab8cded204489..af57b0d99ce9dc09cdbfeadba65fa6b08dba6966 100644 --- a/README.md +++ b/README.md @@ -1,175 +1,165 @@ + + # 前端监控 SDK +## 简介 + +这是一个用于前端监控的 SDK，支持手动上报、爆光埋点、动态节点手动绑定监听、无痕埋点、用户行为录制、行为录制回放等功能。 + ## 安装 -```npm -npm i @fe-hl/monitor-sdk -S +你可以使用以下命令安装 SDK： + +```bash +npm install fe-monitor-sdk ``` -## 参数说明 +或者 -| 参数 | 是否必传 | 默认值 | 说明 | -| :--------------------------- | :------: | :----: | :------------------------------: | -| pId | true | - | 产品 ID | -| reportUrl | true | - | 上报接口地址 | -| reportInterval | false | 30 | 上报间隔`默认30秒` | -| batchSize | false | 20 | 每次上报的最大条数`默认20条` | -| debug | false | false | debug 模式打印控制台，不上报接口 | -| jsErrorLog | false | false | js 异常 | -| promiseErrorLog | false | false | promise 异常 | -| resourcesErrorLog | false | false | 资源加载异常 | -| exposureLog | false | false | 曝光埋点 | -| automaticBurialPointLog | false | false | 自动埋点 | -| pageDwellTimeLog | false | false | 页面停留时间 | -| pvLog | false | false | pv | -| xhrLog | false | false | 接口监控 | -| resourcesPerfLog | false | false | 资源加载性能 | -| perfLog | false | false | 页面渲染性能 | -| longTaskLog | false | false | 长任务 | -| behaviorRecorderLog`(1.3.0)` | false | false | 用户行为录制 | -| sampleRate | false | 如下 | 抽样上报比例 | - -## sampleRate 抽样上报比例 - -- 默认值：`0.5`，即上报 50%，`1` 即上报 100% - -| 参数 | 默认值 | 说明 | -| :------------------- | :----: | :----------: | -| exposure | 1 | 曝光埋点 | -| automaticBurialPoint | 1 | 自动埋点 | -| pageDwellTime | 1 | 页面停留时间 | -| pv | 1 | pv | -| behaviorRecorder | 1 | 用户行为录制 | -| xhr | 0.5 | 接口监控 | -| resourcesPerf | 0.5 | 资源加载性能 | -| perf | 0.5 | 页面渲染性能 | - -## 使用 - -```js -import MonitorSdk from '@fe-hl/monitor-sdk'; - -const monitorSdk = MonitorSdk({ - pId: '1000', // 产品ID - reportUrl: 'http://127.0.0.1:9001/report', // 上报的地址 - debug: false, // 是否开启debug，开启后打印控制台不上报 - jsErrorLog: true, // js异常 - promiseErrorLog: true, // promise异常 - resourcesErrorLog: true, // 资源加载异常 - exposureLog: true, // // 曝光 - automaticBurialPointLog: true, // 自动埋点 - pageDwellTimeLog: true, // 页面停留时间 - pvLog: true, // PV - xhrLog: true, // 接口监控 - resourcesPerfLog: true, // 资源加载性能 - perfLog: true, // 页面渲染性能 - longTaskLog: true, // 长任务 - behaviorRecorderLog: true, // 用户行为录制 -}); +```bash +yarn add fe-monitor-sdk ``` -## 手动上报 +## 参数说明 + +- `sampleRate`: 抽样上报比例，控制上报的数据量。 + +## 使用方法 + +### 手动上报 + +你可以使用 SDK 提供的方法进行手动上报： -```js -import { monitorSdk } from '@fe-hl/monitor-sdk'; +```javascript +import { report } from 'fe-monitor-sdk'; -// 自定义上报 -monitorSdk.report({ - type: 'click', // 类型必填 - message: '下单成功', +report({ + // 上报参数 }); ``` -## 爆光埋点 +### 爆光埋点 -- 给需要`爆光`的元素加上`data-exposure`属性，当元素在可视区域内，上报接口 +用于监控页面元素的爆光情况。 -```html -
广告
-
广告
+```javascript +import { Exposure } from 'fe-monitor-sdk'; + +const exposure = new Exposure(); +exposure.track(); ``` ### 动态节点手动绑定监听 -- **forceObservers**:当动态生成的节点需要监听曝光时，需要手动绑定监听 -- 目前已经通过`MutationObserver`实现动态节点智能监听，无需手动绑定 +允许你手动绑定监听器到动态生成的节点上。 -```js -import { monitorSdk } from '@fe-hl/monitor-sdk'; +```javascript +import { AutomaticBurialPoint } from 'fe-monitor-sdk'; -monitorSdk.forceObservers(); +const autoBurial = new AutomaticBurialPoint(); +autoBurial.bindListeners(); ``` -## 无痕埋点 +### 无痕埋点 -- 当元素发生点击事件，如果元素有`data-track`属性会自动上报接口 +自动监控页面上的用户行为，无需手动绑定。 -```html - - 无痕埋点 - +```javascript +import { RegisterMonitorSdk } from 'fe-monitor-sdk'; - - 无痕埋点 - +const monitor = new RegisterMonitorSdk({ + // 配置项 +}); ``` -## 用户行为录制 +### 用户行为录制 -- **behaviorRecorder**:开启用户行为录制 -- 对用户界面操作流程进行录制，并生成行为日志，用于后续分析用户行为 +记录用户的操作行为，用于后续分析。 -```js -import { monitorSdk } from '@fe-hl/monitor-sdk'; +```javascript +import { BehaviorRecorder } from 'fe-monitor-sdk'; -monitorSdk.behaviorRecorder.start(); // 开始录制 -monitorSdk.behaviorRecorder.stop(); // 停止录制并且上报 +const behaviorRecorder = new BehaviorRecorder(); +behaviorRecorder.start(); ``` ### 行为录制回放 -```js -import rrwebPlayer from 'rrweb-player'; -import 'rrweb-player/dist/style.css'; -let replayer = new rrwebPlayer({ - target: document.getElementById('player'), // 回放容器(建议的尺寸1060*760) - props: { - events, // 上报的数据 - }, -}); +回放用户的行为录制，用于调试或分析。 + +```javascript +behaviorRecorder.replay(); ``` ## 性能关键指标优化说明 -| 指标 | 计算方式 | 说明 | -| ---- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -| TTFB | `responseStart - redirectStart` | **首字节时间**：从页面重定向开始到接收服务器返回的第一个字节的时间差 | -| FP | `responseEnd - fetchStart` | **首次绘制时间&白屏时间**：浏览器将第一个像素（通常是背景色）绘制到屏幕的时间，反映白屏阶段时长 | -| FCP | 通过 `web-vitals` 库测量 | **首次内容绘制**：浏览器首次渲染出 DOM 内容的时间（如文本、图像等） | -| FMP | 通过 `web-vitals` 库测量 | **首次有意义绘制**：主要内容完成渲染的时间点（主观指标，通常对应核心内容可见或可交互时刻） | -| LCP | 通过 `web-vitals` 库测量 | **最大内容渲染**：视窗内最大内容元素（如图片/标题块）完成渲染的时间（动态指标，随加载过程更新） | -| DCL | `domContentLoadedEventEnd - domContentLoadedEventStart` | **DOM 解析耗时**：DOMContentLoaded 事件从开始到结束的持续时间（反映 DOM 树构建速度） | -| L | `loadEventStart - fetchStart` | **页面完全加载时间**：从开始加载到 load 事件触发的时间（包含所有资源加载） | -| TTI | 通过 `web-vitals` 库测量 | **首次可交互时间**：页面达到完全可交互状态的时间（需满足 FP 完成+主线程空闲+元素可操作） | -| FID | 通过 `web-vitals` 库测量 | **首次输入延迟**：用户首次交互操作（点击/输入）到浏览器实际响应的延迟时间 | - ### TTI 触发条件详解 -1. **首次绘制完成**：页面已完成至少一个像素的渲染（FP 阶段结束） -2. **主线程空闲**：浏览器主线程连续空闲时间 ≥ 50ms（无长任务阻塞） -3. **元素可操作**：关键交互元素（按钮/输入框等）可即时响应用户操作 - → 当三项条件同时满足时，TTI 被记录 +TTI（Time to Interactive）是衡量网页加载性能的重要指标，表示页面从开始加载到可交互的时间。 ### FID 测量原理 -1. **用户首次交互**：监测页面生命周期中的第一次用户操作（点击/触摸/键盘输入） -2. **主线程阻塞检测**：若交互发生时主线程正执行长任务（JS 执行/渲染等），记录任务结束到响应开始的延迟 -3. **阈值判定**：实际延迟 = 浏览器开始处理输入事件的时间戳 - 用户交互时间戳 +FID（First Input Delay）测量用户首次与页面交互时的延迟，用于评估页面的响应能力。 ## 指标参考 -| 指标 | 优 | 中 | 差 | 说明 | -| :--- | ---------: | :----------: | :--------: | :----------: | -| TTFB | 0-800(ms) | 800-1800(ms) | 1800-~(ms) | 第一字节时间 | -| FCP | 0-1.8(sec) | 1.8-3.0(sec) | 3.0-~(sec) | 首次内容绘制 | -| FID | 0-100(ms) | 100-300(ms) | 300-~(ms) | 首次输入延迟 | +请参考性能文档以获取更多关于性能指标的详细信息。 + +## 示例 + +我们提供了 React 和 Vue 的示例应用，帮助你更好地理解和使用 SDK： + +- `examples/react-monitor`: 使用 React 的示例应用。 +- `examples/vue-monitor`: 使用 Vue 的示例应用。 + +## 构建与发布 + +构建工具使用 Rollup，配置文件为 `rollup.config.js`。 + +使用以下命令构建项目： + +```bash +npm run build +``` + +或者 + +```bash +yarn build +``` + +## 开发环境 + +我们使用 Vite 构建开发环境，你可以使用以下命令启动开发服务器： + +```bash +npm run dev +``` + +或者 + +```bash +yarn dev +``` + +## 测试 + +你可以运行以下命令进行测试： + +```bash +npm test +``` + +或者 + +```bash +yarn test +``` + +## 贡献 + +欢迎贡献代码！请阅读我们的 [贡献指南](CONTRIBUTING.md) 以了解如何提交 Pull Request。 + +## 许可证 + +本项目使用 [MIT License](LICENSE)。 \ No newline at end of file