安装浏览器 SDK
TraceVista Browser SDK 是一个直接运行在浏览器中的轻量监控客户端。最推荐的方式是使用带 API Key 的 Script 标签：配置少、框架无关，并且能尽早观察页面加载过程。
Script 标签接入
<script
defer
src="https://apm.noxussj.top/monitor.min.js"
data-project-key="mk_your_project_key">
</script>
请从网站设置中复制完整代码，替换示例中的 API Key。SDK 默认把数据发送到脚本所在域名的 /api。
加载后，全局对象 window.TraceVista 可用于业务事件和主动错误捕获。
API Key 与绑定域名
每个 API Key 只属于一个监控网站。SDK 上报访问、事件、性能和错误时，服务端会用 API Key 找到该网站，并校验请求来源是否与网站设置中的域名一致：
- 优先读取请求头
Origin，没有可用值时再读取Referer。 - 从请求头中只提取 hostname；协议和端口不参与比较。
- hostname 会转为小写并移除末尾的
.，然后与绑定域名进行完全相等比较。
绑定域名只匹配同名 hostname。example.com、www.example.com 和 app.example.com 是三个独立域名，不会按主域名或上下级关系自动放行：
| API Key 绑定域名 | 页面来源 | 结果 |
|---|---|---|
example.com | https://example.com | 通过 |
www.example.com | https://www.example.com | 通过 |
app.example.com | http://app.example.com:3000 | 通过，协议和端口不参与匹配 |
example.com | https://www.example.com | 403，hostname 不相等 |
www.example.com | https://example.com | 403，hostname 不相等 |
app.example.com | https://www.example.com | 403，hostname 不相等 |
example.com | http://localhost:3000 | 403，hostname 不相等 |
www 和其他子域名不是别名。请按照用户实际打开页面时地址栏中的 hostname 填写网站域名。
运行时配置接入
需要在脚本加载前动态配置时，可以先声明 TraceVistaConfig：
<script>
window.TraceVistaConfig = {
projectKey: 'mk_your_project_key',
debug: false,
autoTrack: true
}
</script>
<script defer src="https://apm.noxussj.top/monitor.min.js"></script>
运行时配置优先于 Script 的 data-* 属性。
高级：手动初始化
默认接入不需要调用 init()；复制带 data-project-key 的 Script 代码即可自动启动。只有当脚本加载时还无法确定 API Key，或必须等用户授权后才启动监控时，才需要手动初始化：
window.TraceVista.init({
projectKey: 'mk_your_project_key',
apiBase: 'https://apm.noxussj.top',
debug: false,
autoTrack: true
})
重复调用 init() 会先停止之前的客户端，再创建新的活动客户端。
自动采集启动过程
SDK 初始化后会安装：
- 全局运行时和 Promise 错误监听
- 资源加载错误监听
- Fetch 与 XMLHttpRequest 错误包装
- PerformanceObserver 性能监听
- History API 单页应用路由监听
当 autoTrack 为 true 时，如果 DOM 仍在解析，SDK 会等待 DOMContentLoaded 后记录首次访问；否则立即记录。
验证安装
在浏览器控制台运行：
window.TraceVista.version
typeof window.TraceVista.track
正确加载后会看到版本字符串和 "function"。随后打开浏览器 Network 面板，刷新页面，确认存在发送到 /api/stats/track 的请求。
一次成功的页面访问上报请求体大致包含：
{
"visitor_id": "v_...",
"session_id": "s_...",
"page_view_id": "pv_...",
"url": "https://example.com/products",
"path": "/products",
"title": "Products",
"viewport_width": 1440,
"viewport_height": 900,
"sdk_version": "1.0.0"
}
403 排查
如果 Network 面板中的 /api/stats/track、/api/events/track、/api/vitals/track 或 /api/errors/track 返回 403：
- 打开该请求的 Response，查看服务端返回的
message，不要只看浏览器的Failed to load resource通用提示。 - 在 Request Headers 中找到
Origin；如果没有，再检查Referer。 - 对照网站设置中的绑定域名，确认两边 hostname 完全一致，尤其检查
www、其他子域名和预览域名。 - 确认页面使用的是该监控网站生成的 API Key，而不是另一个环境或项目的 Key。
常见响应：
{"message":"APIKEY 与当前网站域名不匹配"}
这表示接口可访问，但请求来源未通过域名校验。修改网站绑定域名或换用与当前来源对应的网站 API Key 后再刷新页面。
如果响应提示账号已禁用，则需要先恢复账号状态；它与域名匹配无关。如果没有看到上报请求，请继续检查 API Key、CSP、SDK 请求状态和浏览器控制台，也可以暂时开启 调试配置。