Web SDK 接入

方式一：npm（有构建流程）

npm i @ms-monitor/web

方式二：<script> 标签（无构建工具）

静态 HTML / WordPress / 老 JSP·PHP / 低代码平台等无打包流程的站点，直接用 IIFE 产物 ms.min.js，data-* 属性配置、自动初始化：

<!-- 监控域名自托管：部署自带 /sdk/，dsn 自动推导可省略 -->
<script defer src="https://monitor.example.com/sdk/ms.min.js"
        data-app-id="my-app" data-token="创建应用时返回的 token"></script>

<!-- 或公共 CDN（包发布在 npmjs）：跨域托管必须显式给 data-dsn -->
<script defer src="https://cdn.jsdelivr.net/npm/@ms-monitor/web@0/dist/ms.min.js"
        data-app-id="my-app" data-token="创建应用时返回的 token"
        data-dsn="https://monitor.example.com/api/v1/collect"></script>

data-* 对应初始化配置：data-app-id（必填）、data-token、data-dsn、data-release、data-env、data-user-id；data-track/data-performance/data-breadcrumbs 给 "false" 可关，data-white-screen 给 "true" 显式开，data-auto-init="false" 关闭自动初始化只暴露 window.msMonitor。

也可完全手动初始化（同 npm 用法）：msMonitor.init({ appId, token, dsn })，返回的 client 与 msMonitor.client 是同一个。

固定版本 + SRI

ms.min.js 随服务端升级变化，与其配 integrity（每次升级即失效）不如直接用版本化产物——文件名即内容指纹，可安全加 SRI：

<!-- 自托管固定版（旧版本文件保留，固定后仍可上报；crossorigin/data-dsn 跨域必需） -->
<script defer src="https://monitor.example.com/sdk/ms-0.2.0.min.js"
        integrity="sha384-…" crossorigin="anonymous"
        data-app-id="my-app" data-token="…"
        data-dsn="https://monitor.example.com/api/v1/collect"></script>

<!-- CDN 固定版（npm 版本不可变；跨域 SRI 必须带 crossorigin） -->
<script defer src="https://cdn.jsdelivr.net/npm/@ms-monitor/[email protected]/dist/ms.min.js"
        integrity="sha384-…" crossorigin="anonymous"
        data-app-id="my-app" data-token="…"
        data-dsn="https://monitor.example.com/api/v1/collect"></script>

integrity 从 {监控域名}/sdk/manifest.json 获取；后台「接入指引」Script 标签 tab 会自动生成这两条。自托管同源场景 SRI 收益有限（能改同源文件者已控制源站），主要价值是 CDN 防投毒。

初始化

在应用入口尽早调用（路由注册之前）：

import { init } from '@ms-monitor/web';

const client = init({
  appId: 'my-app',                                    // 管理后台创建应用时获得
  token: '创建应用时返回的 token',                      // 写入鉴权，必填（缺失返回 403）
  dsn: 'https://monitor.example.com/api/v1/collect',  // 采集地址
  release: '1.0.0',                                   // 与 sourcemap 上传的版本一致
});

默认开启：JS/Promise/资源/接口错误、面包屑、Web Vitals、长任务、慢资源、PV/停留/点击行为。

SourceMap 还原

生产构建时自动上传 sourcemap（Vite）：

npm i -D @ms-monitor/sourcemap-upload

// vite.config.ts
import { monitorSourcemapPlugin } from '@ms-monitor/sourcemap-upload';

export default defineConfig({
  build: { sourcemap: true },
  plugins: [
    monitorSourcemapPlugin({
      endpoint: 'https://monitor.example.com/api/v1/sourcemaps',
      appId: 'my-app',
      release: '1.0.0',   // 与 init 的 release 一致
      token: '…',          // 应用的采集 token
    }),
  ],
});

常用 API

client.track('purchase', { sku: 'sku-001', price: 99 });  // 自定义埋点
client.setUser('user-42');                                 // 绑定登录用户
client.flush();                                            // 立即冲刷队列

React 错误边界捕获后也可手动上报：

componentDidCatch(error: Error) {
  client.capture('error', { mechanism: 'framework', message: error.message, stack: error.stack });
}

完整配置见配置项参考。