插件配置

Web SDK 通过 plugin 配置管理各类采集能力的开启状态和具体行为。常见写法是：

true：开启该插件，使用 SDK 内部默认行为；
false：关闭该插件；
object：开启该插件，并传入该插件的子配置。

import Aegis from 'bugly-web-sdk';

// 仅用于 API 监控 ignoreUrls 排除 SDK 自身上报请求，不需要作为 hostUrl.url 传入。
const BUGLY_PRO_REPORT_URL = 'https://pro.bugly.qq.com/collect/aegisV2Web';

const aegis = new Aegis({
  id: '<bugly-app-id>',
  appKey: '<bugly-app-key>',
  buglyType: 'pro',
  plugin: {
    spa: true,
    error: true,
    assetSpeed: true,
    pagePerformance: true,
    webVitals: true,
    session: true,
    blankScreen: true,
    api: {
      apiDetail: false,
      reportWhenError: true,
      ignoreUrls: [BUGLY_PRO_REPORT_URL],
    },
  },
});

buglyType: 'pro' 会让 SDK 使用专业版内置上报地址 https://pro.bugly.qq.com/collect/aegisV2Web 和白名单/远程采样配置地址 https://pro.bugly.qq.com/webconfig/v_web/config。插件配置页中的 BUGLY_PRO_REPORT_URL 仅用于 ignoreUrls 排除 SDK 自身上报请求；一般用户不需要配置 hostUrl。

Web 插件配置

{
  plugin: {
    aid?: boolean | PluginConfigOption;
    pv?: boolean | PluginConfigOption;
    spa?: boolean | PluginConfigOption | { onRouterChange: () => Record<string, any> };
    error?: boolean | PluginConfigOption;
    api?: boolean | ApiPluginConfig;
    assetSpeed?: boolean | PluginConfigOption;
    pagePerformance?: boolean | PluginConfigOption;
    webVitals?: boolean | PluginConfigOption;
    session?: boolean | CoreSessionConfig;
    blankScreen?: boolean | PluginConfigOption;
    device?: boolean | PluginConfigOption;
    close?: boolean | PluginConfigOption;
  }
}

插件项	说明
`aid`	Aegis SDK 为用户设备分配的唯一标识，通常用于区分用户、计算 UV 等
`pv`	页面访问上报
`spa`	单页应用路由变化上报，可通过 `onRouterChange` 自定义路由变化时的附加信息
`error`	JS 执行错误、Promise 错误、资源加载失败等错误采集
`api`	API 请求监控，拦截浏览器 `fetch` 与 `XMLHttpRequest`
`assetSpeed`	静态资源加载性能采集
`pagePerformance`	页面加载性能采集，可配合 `urlHandler` 修正页面 URL
`webVitals`	Web Vitals 指标采集
`session`	会话/用户行为相关数据采集
`blankScreen`	白屏检测
`device`	设备信息采集
`close`	页面关闭相关上报

aid

Aegis SDK 会为每个用户设备分配唯一标识。该标识通常存储在浏览器本地存储中，用于区分用户、计算 UV 等。如果业务需要自行传入设备标识，可在初始化配置或 setConfig 中传入 aid。

const aegis = new Aegis({
  id: '<bugly-app-id>',
  appKey: '<bugly-app-key>',
  aid: '<device-id>',
});

// 或在设备标识生成后更新
aegis.setConfig({
  aid: '<device-id>',
});

pagePerformance

pagePerformance 用于采集页面加载性能。对于包含动态路由、Hash 路由或自定义页面 URL 的应用，可通过全局 urlHandler 或插件子配置中的 urlHandler 统一页面 URL 口径。

new Aegis({
  id: '<bugly-app-id>',
  appKey: '<bugly-app-key>',
  pageUrl: window.location.href,
  urlHandler: () => window.location.pathname,
  plugin: {
    pagePerformance: true,
  },
});

session

session 用于会话相关数据采集。对于 SPA 框架，可结合业务路由、用户行为和应用可见性变化配置会话采集策略。若业务对用户行为采集有合规要求，请在开启前确认采集范围和隐私告知。

new Aegis({
  id: '<bugly-app-id>',
  appKey: '<bugly-app-key>',
  plugin: {
    session: {
      actionTypes: true,
    },
  },
});

API 配置

api 插件用于监控浏览器中的 fetch 和 XMLHttpRequest 请求。配置类型包含以下常用字段：

type ApiPluginConfig = {
  apiDetail?: boolean;
  reportAbort?: boolean;
  reportWhenError?: boolean;
  resourceTypeHandler?: Function;
  retCodeHandler?: Function;
  reqParamHandler?: Function;
  resBodyHandler?: Function;
  reqHeaders?: Array<string>;
  resHeaders?: Array<string>;
  isSSE?: Function;
  isFirstSSEChunk?: Function;
  urlHandler?: (url: string, payload?: any) => string;
  reportUrls?: Array<string | RegExp>;
  ignoreUrls?: Array<string | RegExp>;
  apiDetailReportUrls?: Array<string | RegExp>;
  apiDetailIgnoreUrls?: Array<string | RegExp>;
  injectTraceHeader?: 'traceparent' | 'sw8' | 'b3' | 'sentry-trace';
  injectTraceUrls?: Array<string | RegExp>;
  injectTraceIgnoreUrls?: Array<string | RegExp>;
};

配置项	类型	说明
`api`	`boolean \\| object`	设为 `true` 或对象时开启 API 监控，设为 `false` 时关闭
`apiDetail`	`boolean`	是否采集请求参数、响应内容等详情
`reportAbort`	`boolean`	是否上报被 abort 的请求
`reportWhenError`	`boolean`	是否在接口异常时上报错误数据；SDK 源码中该项默认按 `true` 处理
`retCodeHandler`	`Function(data, url, ctx): { isErr: boolean, code: string }`	自定义业务返回码判断逻辑
`reqParamHandler`	`Function(data, url)`	上报前处理请求参数，可用于脱敏或裁剪
`resBodyHandler`	`Function(data, url, ctx)`	上报前处理响应内容，可用于脱敏或裁剪
`reqHeaders`	`Array<string>`	指定需要上报的请求头字段列表
`resHeaders`	`Array<string>`	指定需要上报的响应头字段列表；非 simple header 需后端返回 `Access-Control-Expose-Headers`
`resourceTypeHandler`	`Function(url)`	自定义请求资源类型判断逻辑
`urlHandler`	`Function(url, payload): string`	自定义最终上报的请求 URL
`reportUrls`	`Array<string \\| RegExp>`	仅收集匹配规则的 API 日志
`ignoreUrls`	`Array<string \\| RegExp>`	忽略匹配规则的 API 日志，建议加入 SDK 上报地址避免自上报干扰
`apiDetailReportUrls`	`Array<string \\| RegExp>`	仅对匹配规则的请求采集详情
`apiDetailIgnoreUrls`	`Array<string \\| RegExp>`	对匹配规则的请求不采集详情
`injectTraceHeader`	`'traceparent' \\| 'sw8' \\| 'b3' \\| 'sentry-trace'`	开启后，SDK 会在匹配请求中注入对应 trace header
`injectTraceUrls`	`Array<string \\| RegExp>`	指定需要注入 trace header 的 URL
`injectTraceIgnoreUrls`	`Array<string \\| RegExp>`	指定不需要注入 trace header 的 URL
`isSSE` / `isFirstSSEChunk`	`Function`	用于 SSE 场景的请求识别和首包判断

敏感信息提醒

apiDetail: true 会采集请求/响应详情。若接口中包含密码、token、手机号、身份证号、内部密钥等敏感字段，必须通过 reqParamHandler、resBodyHandler、apiDetailReportUrls、apiDetailIgnoreUrls 等配置做脱敏、裁剪或范围控制后再开启。

返回码处理示例

假设业务接口返回结构如下：

{
  "code": 0,
  "message": "ok",
  "data": {}
}

可以通过 retCodeHandler 自定义业务错误判断：

new Aegis({
  id: '<bugly-app-id>',
  appKey: '<bugly-app-key>',
  plugin: {
    api: {
      retCodeHandler(data) {
        try {
          if (typeof data === 'string') data = JSON.parse(data);
        } catch (e) {
          return { isErr: true, code: 'parse_error' };
        }

        return {
          isErr: data.code !== 0,
          code: String(data.code),
        };
      },
    },
  },
});

脱敏示例

new Aegis({
  id: '<bugly-app-id>',
  appKey: '<bugly-app-key>',
  plugin: {
    api: {
      apiDetail: true,
      reqParamHandler: (body, url) => {
        const text = typeof body === 'string' ? body : JSON.stringify(body);
        return text.replace(/"token":"[^"]+"/g, '"token":"***"');
      },
      resBodyHandler: (body, url) => {
        try {
          const data = JSON.parse(body);
          delete data.secret;
          delete data.password;
          return JSON.stringify(data);
        } catch (e) {
          return body;
        }
      },
    },
  },
});

插件配置

Web 插件配置​

aid​

pagePerformance​

session​

API 配置​

返回码处理示例​

脱敏示例​