BetterMonitor SDK 使用文档
快速集成前端监控功能
better-monitor 是一个前端日志监控SDK，用于帮助开发者快速集成前端监控功能，代码已完全开源在 GitHub （如有帮助，请 star 支持一下😎）。
- 🔥 错误监控：支持捕获 JavaScript 报错：`error` 和 `unhandledrejection`。
- 🔥 API 监控：支持拦截并记录基于 XMLHttpRequest 对象的接口请求/响应数据（支持 `axios`、`jQuery` 等库）。
- 🔥 行为日志：记录用户操作日志，支持按时间顺序追踪用户行为。
- 🔥 访问统计：自动记录访问统计数据：PV（页面访问量）、UV（独立访客数）和 BV（浏览器/操作系统访问量）。
- 🔥 埋点统计：支持上报埋点查看统计信息。
- 🔥 性能测量：提供时间测量功能，方便追踪性能问题。
注意
该 SDK 需搭配后端服务使用。你可以参考本文档自行实现后端服务，或者使用我们的 在线服务 （适合访问量不大的站点，每月不到一杯奶茶的费用）。使用该 SDK 的开发者（不论是否使用在线服务），请使用微信或企业微信扫描下方二维码加入我们的支持群方便沟通联系：
快速开始
方式一：CDN 引入（推荐）
HTML
<script
crossorigin="anonymous"
src="https://cdn.verysites.com/verybugs/better-monitor/better-monitor.min.js"
></script>TypeScript
if ("BetterMonitor" in window) {
// 初始化 SDK 参数
window.BetterMonitor.init({
// 替换成你的项目ID，其他可配置参数见后文
projectId: 999,
});
}小技巧：如果你只需要上报 JavaScript 错误日志和访问统计数据，只需一行代码即可完成集成，不需要写 JavaScript 代码（SDK 在检测到 `data-project-id` 属性后会自动调用 `window.BetterMonitor.init` 方法进行初始化）：
<script
crossorigin="anonymous"
data-project-id="<你的项目ID>"
src="https://cdn.verysites.com/verybugs/better-monitor/better-monitor.min.js"
></script>方式二：NPM 安装
Bash
# 在项目里安装依赖
npm install -S better-monitorTypeScript
import BetterMonitor from "better-monitor";
// 初始化 SDK 参数
BetterMonitor.init({
// 替换成你的项目ID，其他可配置参数见后文
projectId: 999,
});常用API
1. init
描述：初始化 SDK。
TypeScript
interface ParamsInit {
// 项目ID
projectId: string;
// 是否开启 debug 模式，默认为 `false`
debug?: boolean;
// 是否上报接口日志，默认为 `false`
api?: boolean;
// 是否上报页面访问数据，默认为 `true`
view?: boolean;
// 是否上报错误日志，默认为 `true`
error?: boolean;
// 是否上报行为日志，默认为 `true`
action?: boolean;
// 是否上报埋点数据，默认为 `true`
statistics?: boolean;
// 黑名单，匹配的日志将不会被上报
blackList?: Array<string | RegExp>;
// 用于获取用户ID的函数
getUserId?: (defaultStrategy: () => string) => string;
}
function init(settings: Partial<IStore>): void;2. addBug
描述：添加错误日志。一般情况下你不需要主动调用该方法，因为 SDK 会自动捕获 JavaScript 错误日志。
TypeScript
interface IParamsAddBug {
pageUrl: string;
message: string;
stack: string;
source: string;
type: string;
}
function addBug(params: IParamsAddBug): void;3. printLog, printWarn, printError
描述：打印日志。与 `console.log`、`console.warn` 和 `console.error` 相同。
TypeScript
function printLog(...args: any[]): void;
function printLogDirectly(...args: any[]): void;
function printWarn(...args: any[]): void;
function printWarnDirectly(...args: any[]): void;
function printError(...args: any[]): void;
function printErrorDirectly(...args: any[]): void;4. logTime, logTimeEnd
用法与 `console.time` 和 `console.timeEnd` 类似。
TypeScript
function logTime(label: string): string;
function logTimeEnd(label: string): void;
function logTimeEndDirectly(label: string): void;特性说明
批量上报
SDK 采用批量上报机制，自动将多条日志合并上报，提高性能并减少网络请求：
- API 日志：当队列达到 5 条时自动上报，或在页面卸载时上报。
- 行为日志：当队列达到 10 条时自动上报，或内容超过 10KB 时立即上报，否则延迟 300ms 上报。
支持单页应用（SPA）路由
SDK 会自动监听 SPA 应用的路由变化（`pushState` 和 `hashchange`），自动记录页面访问。
截图预览
PV 统计界面
JS 报错日志
