aegis-web-sdk

Aegis web-sdk-v2 是伽利略团队打造的前端web监控SDK，在原v1版本上进行了大幅度的升级，统一了Web端的数据采集协议和字段，涵盖了错误监控(JS错误、Promise异常、接口异常等)，性能(页面首屏、LCP等指标)、资源测速（img, script, css），接口测速。

在使用 aegis 时无需过多侵入业务代码，做到与业务代码充分解耦。在伽利略平台可进行前端性能观测，结合后台服务可实现前后台串联一体化的观测体验。

Quick start

1. 前往伽利略平台 创建TAMv2 观测target

2. 接入新监控对象，选择 "端服务" -> WEB，创建后获取target, 作为sdk 初始化使用的id。

接入步骤详见 aegis-web-sdk接入

Install

针对业务端的接入使用，SDK 提供了相应的引入方式；建议SDK的初始化提前执行，以便保证SDK能够采集和监控更多的数据。

CDN 方式安装并初始化SDK

CDN资源地址如下：

• 最新版本：https://aegis.cdn-go.cn/aegis-sdk-v2/latest/aegis.min.js

• 特定版本(注意链接中的版本号)：https://aegis.cdn-go.cn/aegis-sdk-v2/{version}/aegis.min.js

• 安全身份识别版本：https://aegis.cdn-go.cn/aegis-sdk-v2/latest/aegis.f.min.js

功能说明：引入浏览器指纹算法，提升uv准确率；增强安全审计功能。

加载后将会在 window 上挂载 Aegis 构造函数。

使用方式：

在 html 文件内添加如下的脚本配置，并且声明初始化处理：

<script src="https://aegis.cdn-go.cn/aegis-sdk-v2/latest/aegis.min.js"></script>
<script>
  // 伽利略海外上报地址https://tgalileo.com/collect，如有需要可替换成这个地址
  const url = "https://galileotelemetry.tencent.com/collect"; // 伽利略上报地址，不变
  const id = 'SDK-7aa0ec19b27e05_example'; // 使用上面项目接入得到的token
  window.AegisV2 = new Aegis({
    id, // 项目token，即上报伽利略监控的唯一标识
    hostUrl: { url },
    plugin: {
      pv: true, // 默认开启pv收集器
      aid: true, // 默认开启aid收集器
      error: true, // 默认开启error收集器
      device: true, // 默认开启device收集器
      close: true, // 默认开启close收集器
      pagePerformance: true, // 默认开启pagePerformance收集器
      webVitals: true, // 默认开启webVitals收集器

      fId: false, // 默认关闭fId指纹插件，开启后对页面性能有损害，非必要不建议开启, 如需开启，设置为 true
      ie: false, // 默认关闭ie兼容插件，如需开启，设置为 true
      spa: false, // 默认关闭spa 上报插件，如需开启，设置为 true
      api: false, // 默认关闭api数据收集插件，如需开启，设置为 true
      assetSpeed: false, // 默认关闭资源测速插件，如需开启，设置为 true
      session: false, // 默认关闭session插件，如需开启，设置为 true
    },
});
</script>

npm 方式安装并初始化SDK

可使用npm、yarn等包安装工具安装，安装之前请确认已经配置了腾讯源: https://mirrors.tencent.com/npm/ 作为 npm registry

npm install @tencent/aegis-web-sdk-v2

使用方式：

import Aegis from '@tencent/aegis-web-sdk-v2';

// 伽利略海外上报地址https://tgalileo.com/collect，如有需要可替换成这个地址
const url = "https://galileotelemetry.tencent.com/collect"; // 伽利略上报地址，不变
const id = 'SDK-7aa0ec19b27e05_example'; // 上报id
window.Aegis = new Aegis({
    id, // 项目ID，即上报id
    hostUrl: { url },
    plugin: {
      pv: true, // 默认开启pv收集器
      aid: true, // 默认开启aid收集器
      error: true, // 默认开启error收集器
      device: true, // 默认开启device收集器
      close: true, // 默认开启close收集器
      pagePerformance: true, // 默认开启pagePerformance收集器
      webVitals: true, // 默认开启webVitals收集器

      fId: false, // 默认关闭fId指纹插件，开启后对页面性能有损害，非必要不建议开启
      ie: false, // 默认关闭ie兼容插件，如需开启，设置为 true
      spa: false, // 默认关闭spa 上报插件，如需开启，设置为 true
      api: false, // 默认关闭api数据收集插件，如需开启，设置为 true
      assetSpeed: false, // 默认关闭资源测速插件，如需开启，设置为 true
      session: false, // 默认关闭session插件，如需开启，设置为 true
    },
});

Usage

aegis-web-sdk 提供了丰富的钩子配置和API使用，支持业务的多场景使用，详见 aegis-web-sdk使用文档

Session action 标记与强制上报

Session 插件会优先读取 data-aegis-action-name 作为操作名称。可额外使用 data-aegis-action-tag 为关键操作设置稳定的业务标记，并按配置绕过 action 的随机采样：

<button
  data-aegis-action-name="提交订单"
  data-aegis-action-tag="checkout.submit"
>
  提交订单
</button>

new Aegis({
  plugin: {
    session: {
      actionTag: {
        forceReportTags: ['checkout.submit', 'payment.confirm'],
        maxForcedActionsPerSession: 20,
        maxForcedActionsPerMinute: 10,
        onLimitExceeded: 'sample',
      },
      actionLocator: {
        maxDepth: 10,
        includeId: true,
        includeClassName: true,
      },
    },
  },
});

命中的 action 会携带 action_tag。 未命中的操作继续遵循 session 插件原有采样率；达到限额后按 onLimitExceeded 回退至随机采样（sample）或丢弃（drop）。forceReportTags: ['*'] 可显式匹配全部 tag。 Tag 应使用稳定、低基数的标识，例如 checkout.submit，不要包含用户、订单或 URL 等动态数据。

配置 actionLocator 后，SDK 会在 action span 中上报 action_target_path。它是从根节点到实际 点击元素的 CSS 风格路径，每一层已包含元素名、可用的 id、class 与同类节点序号，无需重复上报独立的 id/class 字段。路径采集默认关闭，避免无感收集高基数 DOM 信息；应仅在确认 id/class 不含用户或业务 敏感标识后开启。

Contributing

如果需要共建端监控，可以访问端监控OTeam了解和参与。