SDK 接入
SDK API 参考
查看 track、captureError、getOverview 和 version 的使用场景、返回值与示例数据。
SDK 加载后会暴露 window.TraceVista。这页只列稳定公开 API；未列出的 Client 属性和内部方法不属于公开契约，后续版本可能变更。
track()
记录自定义业务事件。页面访问、性能和错误会自动采集；track() 只用于产品自身关心的业务行为。
track(
eventName: string,
data?: Record<string, unknown>,
options?: { path?: string }
): Promise<boolean>
const accepted = await window.TraceVista.track('plan_selected', {
plan: 'professional',
placement: 'pricing_page'
})
- 事件名不能为空，最长 100 个字符。
- 自定义数据会进行安全序列化，并自动附加
_tracevista上下文。 - 返回
true表示接口接受本次上报。
什么时候会用到：
- 记录转化漏斗：注册按钮点击、套餐选择、支付结果。
- 记录关键业务动作：创建项目、生成 KEY、提交表单。
- 用
options.path把事件归到指定业务页面。
上报后的 data 大致类似：
{
"plan": "professional",
"placement": "pricing_page",
"_tracevista": {
"visitor_id": "v_...",
"session_id": "s_...",
"page_view_id": "pv_...",
"url": "https://example.com/pricing",
"path": "/pricing"
}
}
captureError()
主动捕获已经被业务代码处理的异常。全局运行时错误、Promise rejection、资源错误和接口错误会自动采集；captureError() 用来补充那些已经被业务代码 catch 住、不会再冒泡的错误。
captureError(
error: Error | string | unknown,
extra?: Record<string, unknown>
): Promise<boolean>
await window.TraceVista.captureError(error, {
module: 'profile',
operation: 'save_avatar'
})
什么时候会用到：
try/catch已经兜底了错误，但仍希望在后台看到它。- 第三方 SDK、支付、登录、上传等关键链路失败，需要带上业务上下文。
- 业务把错误转换成 toast 或 fallback UI 后，需要保留排查线索。
上报的错误 data 大致类似：
{
"name": "Error",
"stack": "Error: save failed\n at ...",
"context": {
"visitor_id": "v_...",
"session_id": "s_...",
"page_view_id": "pv_...",
"url": "https://example.com/profile",
"path": "/profile"
},
"breadcrumbs": [
{
"type": "click",
"at": "2026-07-30T08:12:30.000Z",
"data": {
"element": "button#save"
}
}
],
"extra": {
"module": "profile",
"operation": "save_avatar"
}
}
getOverview()
查询网站公开访问概览，包括统计起始时间、今日和累计 PV/UV；查询失败时返回 null。
getOverview(): Promise<object | null>
const overview = await window.TraceVista.getOverview()
什么时候会用到：
- 在被监控网站前台展示轻量访问统计。
- 做公开状态页或自检面板，只需要简单 PV/UV，不需要登录管理端。
- 接入完成后快速确认项目 KEY 对应的统计接口可读。
返回数据大致类似：
{
"data": {
"started_at": "2026-07-25 03:21:09.123",
"today": {
"pv": 36,
"uv": 12
},
"total": {
"pv": 1280,
"uv": 342
}
}
}
完整分析、错误记录、性能详情和配额信息请使用管理端，不建议在前台页面直接承载这些能力。
version
当前 SDK 构建版本字符串：
console.log(window.TraceVista.version)
什么时候会用到：
- 排查线上问题时确认用户页面加载的是哪个 SDK 版本。
- 客服或错误记录里需要附带 SDK 版本，方便判断是否已升级。
- 对比 CDN、缓存和管理端静态文件是否同步。
示例：
1.0.0