H5 SDK

HealthGuard Web SDK 用于在浏览器（H5）环境中采集错误、请求和性能数据。

安装

npm install @health-guard/sdk-web

基础用法

import { createHealthGuardClient } from '@health-guard/sdk-web';

const client = createHealthGuardClient({
  appKey: 'your-app-key',
  endpoint: 'https://your-collector.com/api/events/batch',
  autoCapture: true
});

配置选项

选项	类型	必填	默认值	说明
appKey	string	是	-	应用唯一标识
endpoint	string	是	-	Collector 上报地址
release	string	否	-	应用版本号
environment	string	否	-	环境：development / test / production
userId	string	否	-	业务用户标识
autoCapture	boolean | object	否	false	是否自动捕获错误和请求
flushIntervalMs	number	否	5000	批量上报间隔（毫秒）
maxBatchSize	number	否	10	单次上报最大事件数
transportFailureRetryDelayMs	number	否	30000	transport 失败后回队等待重试的间隔（毫秒）

autoCapture 选项

当 autoCapture 为 true 时，开启全部自动采集：

autoCapture: {
  errors: true,           // window.onerror
  unhandledRejections: true,  // unhandledrejection
  fetch: true,            // 拦截 fetch
  xhr: true               // 拦截 XMLHttpRequest
}

手动上报 API

captureException(error)

手动上报一个错误：

try {
  riskyOperation();
} catch (err) {
  client.captureException(err);
}

captureHttp(input)

手动上报一次 HTTP 请求：

client.captureHttp({
  method: 'POST',
  url: '/api/users',
  status: 500,
  duration: 240,
  success: false,
  errorMessage: 'Internal Server Error'
});

capturePerformance(input)

手动上报一个性能指标：

client.capturePerformance({
  name: 'LCP',
  value: 1200,
  rating: 'good'
});

addBreadcrumb(breadcrumb)

添加一条面包屑：

client.addBreadcrumb({
  type: 'navigation',
  message: 'User navigated to /checkout',
  data: { from: '/cart' }
});

flush()

立即刷新队列，上报所有未发送事件（包括 transport 失败后重新入队的事件）：

await client.flush();

隐私与脱敏

SDK 默认对以下字段进行脱敏处理：

• URL Query 中的 authorization, password, token, secret, cookie 等
• 不上报 request body 和 response body
• 使用业务方传入的 userId 或匿名 ID，不采集真实身份信息

网络诊断（未发布源码）

2026-10-14 源码新增诊断与补传能力，配置方式、发布状态和不可用字段见 网络诊断。Flutter 接入见 Flutter SDK。