SDK接入指南

简介

Bugly Web SDK 用于在浏览器环境中监控 Web 应用的质量和性能信息，并将数据上报到 Bugly,并支持以插件方式开启页面访问、JS 错误、Promise 错误、资源加载、接口请求、页面性能、Web Vitals、会话、白屏等数据采集。

SDK接入

创建产品

打开 Bugly 的控制管理台，进入我的产品列表，点击右上角的创建产品按钮创建新产品。

产品创建后，可在产品信息页查看该产品的 APP ID 和 APP KEY。

APP ID 和 APP KEY 是 SDK 与 Bugly 服务端通信的重要凭证，也是识别一个产品的唯一标识。

安装SDK

使用 npm 安装 SDK

npm install --save bugly-web-sdk@1.0.2

使用 pnpm 安装 SDK

在 package.json 中添加依赖：

{
  "dependencies": {
    "bugly-web-sdk": "1.0.2"
  }
}

然后安装依赖：

pnpm install

提醒

当前 Web SDK 文档以 npm/pnpm 安装和模块化导入为主。请不要臆造 CDN 接入方式；如后续 SDK 发布 CDN 接入能力，再以 SDK 发布说明为准补充。

SDK使用

Web SDK 运行在浏览器环境中。专业版设置 buglyType: 'pro' 后，SDK 会自动使用内置上报地址，一般不需要配置 hostUrl。

import Aegis from 'bugly-web-sdk';

const aegis = new Aegis({
  id: 'xxx', // 产品对应的 APP ID，必填
  appKey: 'xxx', // 产品对应的 APP KEY，必填
  uid: 'uid', // 用户 ID，选填
  aid: 'deviceID', // 设备 ID，选填
  buglyType: 'pro', // 上报通道，专业版使用 pro，必填
  env: 'debug', // 默认为 production，设置为 debug 时输出 SDK 日志
  extField: {
    appVersion: '1.0.0', // 应用版本，选填
    bundleId: 'web-app',
  },
  plugin: {
    spa: true, // 开启页面访问数据采集
    error: true, // 开启 JS 错误数据采集
    assetSpeed: true, // 开启静态资源数据采集
    pagePerformance: true, // 开启页面加载数据采集
    webVitals: true, // 开启页面性能数据采集
    session: true, // 开启会话追踪数据采集
    blankScreen: true, // 开启白屏数据采集
    api: {
      apiDetail: false, // 是否上报 API 请求和响应的详细参数
      reportWhenError: true, // API 请求异常时上报
    },
  },
});
window.Aegis= aegis;

对于 Next.js、Nuxt、Remix 等包含 SSR/SSG 的框架，请将上述初始化代码放在浏览器生命周期或客户端插件中执行，避免在服务端渲染阶段初始化 SDK。

配置方法

SDK 实例化时传入 WebConfig 配置对象。常用字段如下：

配置项	说明
id	产品 APP ID，必填
appKey	产品 APP KEY，必填
buglyType	上报通道标识，专业版使用 'pro'（即 SDK 导出的 HOST_TYPE.PRO）；不配置 hostUrl.url 时，SDK 会根据 buglyType 使用内置上报/白名单地址
env	运行环境，例如 development、test、production
uid	用户 ID，可在登录后通过 setConfig 更新
aid	设备 ID，如业务已有稳定设备标识可传入
extField	扩展字段，例如 appVersion、bundleId
plugin	插件开关与插件配置，详见「插件配置」
hostUrl	高级自定义配置，仅私有化、临时联调或 SDK 维护者明确要求时使用；一般用户不需要配置

内置地址与 hostUrl

Web SDK 会把未传入的 hostUrl 归一为空对象，并在 hostUrl 是对象且没有 url 时，根据 buglyType 设置内置地址。专业版使用 buglyType: 'pro' 时，内置映射为：

类型	上报地址	白名单/远程采样配置地址
buglyType: 'pro'	https://pro.bugly.qq.com/collect/aegisV2Web	https://pro.bugly.qq.com/webconfig/v_web/config
buglyType: 'test'	https://t.rmonitor.qq.com/collect/aegisV2Web	https://t.rmonitor.qq.com/webconfig/v_web/config

测试环境只有在确需接入测试上报通道时才使用 buglyType: 'test'。专业版线上或常规接入请使用 buglyType: 'pro'。

一般用户不需要配置 hostUrl。只有私有化部署、临时联调或需要接入非内置地址时，才使用 hostUrl 做高级自定义：

new Aegis({
  id: '<bugly-app-id>',
  appKey: '<bugly-app-key>',
  buglyType: 'pro',
  hostUrl: {
    url: 'https://example.com/collect/aegisV2Web',
    whiteListUrl: 'https://example.com/webconfig/v_web/config',
  },
});

配置了 hostUrl.url 后会覆盖 buglyType 的内置映射；此时也应同步配置 hostUrl.whiteListUrl，避免远程采样/白名单配置仍指向不符合预期的地址。

setConfig

很多情况下，页面初始化时还拿不到用户的 uid。建议先初始化 SDK，待登录态或用户信息返回后再通过 setConfig 更新，避免初始化前发生的错误无法被 SDK 捕获。

const aegis = await initBuglyAegis();

// 拿到用户信息后更新配置
aegis?.setConfig({
  uid: userInfo.id,
  aid: deviceId,
  extField: {
    appVersion: appVersion,
    bundleId: 'web-app',
  },
});

日志

Web SDK 导出 LoggerLevel，可以通过 logHandler 接收 SDK 运行日志。日志级别从低到高可参考 LoggerLevel.ERROR、LoggerLevel.INFO、LoggerLevel.DEBUG。

import Aegis, { LoggerLevel } from 'bugly-web-sdk';

const aegis = new Aegis({
  id: '<bugly-app-id>',
  appKey: '<bugly-app-key>',
  buglyType: 'pro',
  logHandler: (level: LoggerLevel, message: string) => {
    if (level <= LoggerLevel.INFO) {
      console.log('[Bugly Aegis]', message);
    }
  },
});

建议业务在开发环境输出更详细的 SDK 日志，在线上环境仅保留必要的错误或状态信息，避免控制台噪音过多。