Bonree Frontend Monitoring SDK

博睿前端监控 SDK，用于实时用户监控（RUM），采集页面性能、网络请求、用户行为、异常错误等数据。

版本

当前版本：2.7.0

安装

NPM 安装

npm install bonree-agent

快速开始

ES Module 方式

import BonreeRUM, { BonreeStart, setUserID, setCustomEvent } from 'bonree-agent';

// 初始化 SDK
BonreeStart({
  appId: 'your-app-id',
  appName: 'Your App Name',
  appVersion: '1.0.0',
  uploadAddrHttps: 'https://oneupload.bonree.com/RUM/upload',
  uploadAddrHttp: 'http://oneupload.bonree.com/RUM/upload',
  isDebuge: false
});

// 设置用户 ID
setUserID('user-123');

// 上报自定义事件
setCustomEvent('button_click', 'Login Button', 'clicked');

Script 标签方式

<script src="./BonreeSDK_JS.min.js"></script>
<script>
    window.BonreeStart({
        appId: 'your-app-id',
        uploadAddrHttps: 'https://oneupload.bonree.com/RUM/upload',
        uploadAddrHttp: 'http://oneupload.bonree.com/RUM/upload'
    });
</script>

配置参数

基础配置

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | appId | string | 是 | 应用 ID，从博睿平台获取 | | appName | string | 否 | 应用名称 | | appVersion | string | 否 | 应用版本号 | | uploadAddrHttps | string | 否 | HTTPS 数据上传地址 | | uploadAddrHttp | string | 否 | HTTP 数据上传地址 | | isDebuge | boolean | 否 | 是否开启调试模式，默认 false |

用户配置

| 参数 | 类型 | 说明 | |------|------|------| | userId | string | 用户 ID | | userKey | string | 用户 Key | | extraInfo | string | 附加信息（JSON 字符串） |

数据上报配置

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | cycleTime | number | - | 数据上报周期（秒） | | maxSize | number | - | 最大数据大小（KB） | | probability | number | - | 采样率（千分制，0-1000） | | debounce | number | - | 防抖时间（毫秒） |

会话配置

| 参数 | 类型 | 说明 | |------|------|------| | sessionConfig.inactivityTime | number | 无操作多久切换会话（ms），范围 5000-28800000 | | sessionConfig.maxSessionTime | number | 会话最长时间（ms），范围 5000-28800000 |

隐私配置

| 参数 | 类型 | 说明 | |------|------|------| | ignoreRequestParams | boolean | 是否忽略请求参数 | | ignoreRequestHeaders | boolean | 是否忽略请求头 | | ignoreResources | boolean | 是否忽略资源请求 | | ignoreUserEvents | boolean | 是否忽略用户事件 | | inputValue | array/boolean | 输入框值采集配置 | | findEles | array | 需要添加私有属性的元素配置 |

链路追踪配置

| 参数 | 类型 | 说明 | |------|------|------| | traceConfig.urlTotalList | array | URL 完全匹配列表 | | traceConfig.urlWhiteList | array | URL 白名单 | | traceConfig.urlBlackList | array | URL 黑名单 |

高级配置

| 参数 | 类型 | 说明 | |------|------|------| | enableWebsocket | boolean | 是否启用 WebSocket | | useXHR | boolean | 是否使用 XHR 上传 | | microApp | boolean | 是否启用微应用模式 | | qiankunContainer | string | 微应用容器选择器 | | sm4Config | object | SM4 加密配置 |

API 文档

初始化

BonreeStart(config)

初始化并启动 SDK。

import { BonreeStart } from 'bonree-agent';

BonreeStart({
  appId: 'your-app-id',
  appName: 'Your App',
  appVersion: '1.0.0'
});

用户信息

setUserID(userId)

设置用户 ID。

import { setUserID } from 'bonree-agent';

setUserID('user-123');

setExtraInfo(extraInfo)

设置附加信息（JSON 字符串格式）。

import { setExtraInfo } from 'bonree-agent';

setExtraInfo('{"version":"1.0.0","platform":"web"}');

用户附加信息

setUserExtraInfo(obj)

设置用户附加信息（对象格式）。

import { setUserExtraInfo } from 'bonree-agent';

setUserExtraInfo({
  level: 'VIP',
  points: 1000,
  member: true
});

addUserExtraInfo(key, value)

添加单条用户附加信息。

import { addUserExtraInfo } from 'bonree-agent';

addUserExtraInfo('city', 'Beijing');
addUserExtraInfo('age', 25);

removeUserExtraInfo(key)

移除用户附加信息。

import { removeUserExtraInfo } from 'bonree-agent';

removeUserExtraInfo('city');

increaseUserExtraInfo(key, value)

累加用户附加信息。

import { increaseUserExtraInfo } from 'bonree-agent';

increaseUserExtraInfo('clickCount', 1);

事件属性

addEventAttributes(obj, local?)

添加事件公共属性。

import { addEventAttributes } from 'bonree-agent';

// 添加到内存
addEventAttributes({ environment: 'production' });

// 添加到本地存储
addEventAttributes({ userType: 'premium' }, true);

addEventAttributeWithKey(key, value, local?)

添加单条事件公共属性。

import { addEventAttributeWithKey } from 'bonree-agent';

addEventAttributeWithKey('page', 'home');

removeEventAttributeWithKeys(keys)

移除事件公共属性。

import { removeEventAttributeWithKeys } from 'bonree-agent';

removeEventAttributeWithKeys(['page', 'environment']);

removeAllEventAttributes()

移除全部事件公共属性。

import { removeAllEventAttributes } from 'bonree-agent';

removeAllEventAttributes();

自定义事件

setCustomEvent(eventId, eventName, eventParam?, info?)

上报自定义事件（精简版）。

import { setCustomEvent } from 'bonree-agent';

setCustomEvent('purchase', 'Buy Product', 'product-id-123');

setCustomEventStart(eventId, eventName, eventLabel?, eventParam?, info?)

开始记录自定义事件。

import { setCustomEventStart } from 'bonree-agent';

setCustomEventStart('login', 'User Login', 'form');
// ... 执行登录操作 ...
setCustomEventEnd('login', 'User Login', 'form');

setCustomEventEnd(eventId, eventName, eventLabel?, eventParam?, info?)

结束自定义事件记录。

import { setCustomEventEnd } from 'bonree-agent';

setCustomEventEnd('login', 'User Login', 'form');

自定义页面

setCustomPageStart(pageName, pageAlias?)

开始记录自定义页面。

import { setCustomPageStart } from 'bonree-agent';

setCustomPageStart('Product Detail', 'product-detail-page');

setCustomPageEnd(pageName, pageAlias?)

结束自定义页面记录。

import { setCustomPageEnd } from 'bonree-agent';

setCustomPageEnd('Product Detail', 'product-detail-page');

自定义异常

setCustomException(exceptionType, causedBy?, errorDump?)

上报自定义异常。

import { setCustomException } from 'bonree-agent';

try {
  // 业务代码
} catch (error) {
  setCustomException('BusinessError', 'Failed to process order', error.stack);
}

自定义日志

setCustomLog(logInfo)

上报自定义日志。

import { setCustomLog } from 'bonree-agent';

setCustomLog('User clicked premium button');

自定义指标

setCustomMetric(metricName, metricValue)

上报自定义指标。

import { setCustomMetric } from 'bonree-agent';

setCustomMetric('pageLoadTime', 1200);

H5 性能数据

setCustomH5performanceData(dataInfo)

上报自定义 H5 性能数据。

import { setCustomH5performanceData } from 'bonree-agent';

setCustomH5performanceData({
  pvid: '00000000-0000-0000-0000-000000000000',
  url: 'http://localhost/index.html',
  imd: 1,
  ns: Date.now(),
  ues: -1,
  uee: -1,
  rds: -1,
  rde: -1,
  fs: 3,
  dls: 5,
  dle: 6,
  cs: 7,
  scs: 9,
  ce: 12,
  reqs: 13,
  rsps: 15,
  rspe: 19,
  dl: 20,
  di: 22,
  dcles: 23,
  dclee: 25,
  dc: 26,
  les: 26,
  lee: 35,
  fp: -1,
  fcp: -1,
  lcp: -1
});

路由数据

setCustomRouteChangeData(dataInfo)

上报自定义路由切换数据。

import { setCustomRouteChangeData } from 'bonree-agent';

setCustomRouteChangeData({
  tu: 'http://localhost/index#/home',
  fu: 'http://localhost/index#/',
  d: 2,
  sta: 0,
  al: '',
  pt: '/home',
  rt: 'http://localhost/index/home',
  pu: 'http://localhost/index#/home',
  fw: 'Vue'
});

链路追踪（Span）

startSpan(name, type)

创建执行单元（Span）用于链路追踪。

import { startSpan } from 'bonree-agent';

const span = startSpan('order-process', 'business');

// 设置数据
span.setData('orderId', '12345');
span.setTag('level', 'high');
span.setMetric('amount', 1000, 'yuan');

// 完成执行单元
span.finish(1); // 0: unknown, 1: success, 2: fail

Span 方法说明：

| 方法 | 说明 | |------|------| | finish(status) | 完成执行单元 | | startChild(name, type) | 创建子执行单元 | | setData(key, value) | 设置 Data 数据 | | setTag(key, value) | 设置 Tag 数据 | | setMetric(key, value, unit?) | 设置 Metric 数据 | | removeData(key) | 移除 Data 数据 | | removeTag(key) | 移除 Tag 数据 | | removeMetric(key) | 移除 Metric 数据 | | setStatus(status) | 设置状态 | | setDuration(duration) | 设置耗时（微秒） | | setStatusCode(statusCode) | 设置状态码 |

配置更新

updateConfig(config)

更新 SDK 配置。

import { updateConfig } from 'bonree-agent';

// 动态更新配置
updateConfig({
  isDebuge: true,
  probability: 800
});

操作记录

recordCustomActionEnd()

结束自定义操作。

import { recordCustomActionEnd } from 'bonree-agent';

recordCustomActionEnd();

数据类型

枚举类型

// 平台类型
type OSType = 0 | 1 | 2 | 3 | 4;
// 0: web, 1: android, 2: ios, 3: windows, 4: hos

// Span 执行状态
type SpanStatus = 0 | 1 | 2;
// 0: unknown, 1: success, 2: fail

// 路由切换状态
type RouteStatus = 0 | 2;
// 0: 正常, 2: 异常

完整示例

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Bonree SDK Demo</title>
</head>
<body>
    <h1>Bonree Frontend Monitoring SDK Demo</h1>

    <button id="trackBtn">Track Event</button>
    <button id="errorBtn">Trigger Error</button>

    <script type="module">
        import BonreeRUM, {
            BonreeStart,
            setUserID,
            setExtraInfo,
            setUserExtraInfo,
            addUserExtraInfo,
            addEventAttributes,
            setCustomEvent,
            setCustomException,
            setCustomMetric,
            startSpan,
            updateConfig
        } from 'bonree-agent';

        // 初始化 SDK
        BonreeStart({
            appId: 'your-app-id',
            appName: 'Demo Application',
            appVersion: '1.0.0',
            uploadAddrHttps: 'https://oneupload.bonree.com/RUM/upload',
            uploadAddrHttp: 'http://oneupload.bonree.com/RUM/upload',
            isDebuge: true,
            // 会话配置
            sessionConfig: {
                inactivityTime: 1800000,  // 30分钟无操作切换会话
                maxSessionTime: 3600000    // 最大会话时间 1 小时
            },
            // 隐私配置
            ignoreRequestParams: false,
            inputValue: true
        });

        // 设置用户信息
        setUserID('user-' + Date.now());
        setUserExtraInfo({
            level: 'VIP',
            registerDate: '2024-01-01'
        });
        addUserExtraInfo('lastLogin', new Date().toISOString());

        // 添加事件公共属性
        addEventAttributes({
            environment: 'production',
            region: 'Beijing'
        });

        // 监听按钮点击事件
        document.getElementById('trackBtn').addEventListener('click', () => {
            setCustomEvent('button_click', 'Demo Button', 'clicked');
            setCustomMetric('clickCount', 1);
        });

        // 监听错误事件
        document.getElementById('errorBtn').addEventListener('click', () => {
            try {
                throw new Error('Test error for monitoring');
            } catch (error) {
                setCustomException('DemoError', 'Button click error', error.stack);
            }
        });

        // 使用 Span 进行链路追踪
        const span = startSpan('async-operation', 'business');
        setTimeout(() => {
            span.setData('result', 'success');
            span.setDuration(1500000);  // 1.5 秒
            span.finish(1);
        }, 1500);

        // 动态更新配置
        updateConfig({
            isDebuge: false,
            probability: 500
        });

        console.log('Bonree SDK initialized successfully');
    </script>
</body>
</html>

变更记录

2.7.0

新增功能

许可证

ISC

技术支持

如有问题，请联系博睿技术支持团队。