Skip to Content
快速开始Web SDK

Web SDK（TypeScript）快速开始

浏览器端 SDK。捕获日志、崩溃（自动 window.onerror + unhandledrejection）、Web Vitals 性能、 埋点（含 UTM 自动归因），并能自动给出站 fetch 注入 traceparent 做端到端 Trace。

对应 SDK：sdks/web · 设计：docs/07-design/sdk-web.md

安装

npm install @argus/sdk-web

v0.5 为 git 依赖 / 本地构建；npm 正式发布计划在 v1 后。

初始化（应用入口，只调一次）

import { Argus } from "@argus/sdk-web";
 
Argus.init({
  // 换成你在 Argus Console 拿到的 DSN
  dsn: "argus://demo-public:demo-secret@localhost:4318/demo",
  userId: "user-123",
  appVersion: "1.0.0", // 用于按版本对崩溃分组
});

ArgusConfig 字段：dsn（必填）、userId?、sessionId?、appVersion?、 captureUncaught?（默认 true，自动捕获未处理异常）、captureFetch?（默认 true，自动给出站 fetch 注入 traceparent）、maxEvents?、flushIntervalMs?（默认 10000）。

上报

// 日志（自动进 20 条 breadcrumb 环形缓冲，崩溃时随事件携带）
Argus.log("INFO", "page loaded", { route: "/home" });
Argus.log("ERROR", "payment failed", { reason: "declined" });
 
// 埋点（喂漏斗 / 留存 / 分群）
Argus.track("signup");
Argus.track("add_to_cart", { sku: "ABC-123", price: "29.99" });
 
// 设置用户
Argus.identify("user-456");
 
// 页面卸载前可选 flush
await Argus.flush();

日志级别：DEBUG / INFO / WARN / ERROR / FATAL。

崩溃捕获

自动（默认开启）：captureUncaught: true 时 SDK 安装 window.onerror + unhandledrejection 处理器，未捕获异常以 HMAC 签名上报到 channel='crash'。

手动：

try {
  // ...
} catch (err) {
  Argus.captureCrash({
    errorType: err.constructor.name,
    errorMessage: err.message,
    stacktrace: err.stack,
    attributes: { component: "checkout" }, // 可选
  });
}

UTM 自动归因

Argus.init() 时 SDK 自动从落地页 URL（window.location.search）解析 utm_source / utm_medium / utm_campaign，并附加到每个 track 事件，于是漏斗 / 留存可按获客 渠道在 Console 过滤。

https://app.example.com/?utm_source=google&utm_medium=cpc&utm_campaign=spring
  → 之后每个 Argus.track(...) 都带 utm_source=google ...

端到端 Trace

captureFetch（默认开）会包裹 globalThis.fetch，给非 Argus 出站请求注入 W3C traceparent 并 上报 client span。给非 fetch 的传输手动传播链路用：

// 返回 { traceparent: "00-<trace>-<span>-01" }，注入你自己的请求头
const headers = Argus.traceHeaders();

后端 SDK 会继承这个 traceparent，把端 + 后端串成一条 trace。详见 端到端 Trace 指南。

接入后

在 Console /logs 看日志、/issues 看崩溃聚合、/traces 看链路瀑布图。

概览iOS SDK