🦞 Tracker.js 有哪些新能力

Agent Analytics 的 tracker 刚做了一次比较大的升级。

以前很多需要自定义 JavaScript 才能完成的事情，现在都可以直接用 HTML attributes 配出来，而且我们还补上了一批很适合 instrumentation、QA 和增长分析的新能力。

Declarative Event Tracking

最大的更新是：现在可以不写 JavaScript 就追踪事件。

<button data-aa-event="signup" data-aa-event-plan="pro">
  Sign Up for Pro
</button>

点击按钮后，会直接发送一个 signup 事件，并附带 { plan: "pro" }。

也可以继续通过 data-aa-event-* 添加更多 properties：

<a href="/pricing"
   data-aa-event="cta_click"
   data-aa-event-id="hero_pricing"
   data-aa-event-section="hero">
  See Pricing →
</a>

这意味着不管是开发者还是 AI 代理，都能很轻松地把 tracking 加到页面上。

Outgoing Link Tracking

如果你想知道用户点击了哪些外链，可以直接开启：

<script src="https://api.agentanalytics.sh/tracker.js"
  data-project="my-site"
  data-token="aat_..."
  data-track-outgoing="true"></script>

之后外部链接点击会自动记录成 outgoing_link，并附带 URL、链接文字和目标 hostname。

User Identification

在 signup 或 login 之后，你可以把匿名 session 和真实用户身份关联起来：

window.aa.identify('user_123');

这样，用户注册前后的行为就能被放进同一条旅程里分析。

Rich HTML Experiment Variants

实验现在不只是替换文本，也可以直接切换整段 HTML：

<div data-aa-experiment="hero_test"
     data-aa-variant-b="<h1>Ship Faster</h1><p>Your agent handles the rest</p><img src='/new-hero.png'>">
  <h1>Build Better</h1>
  <p>Analytics your agent can read</p>
  <img src="/hero.png">
</div>

这让你可以测试整块 hero、不同布局甚至更完整的页面段落。

用 URL 强制指定 Variant

做 QA 或截图时，可以直接通过参数锁定某个变体：

https://my-site.com?aa_variant_hero_test=b

这样团队不用等随机分流，也能直接检查某个 variant 的真实渲染效果。

Cross-Domain Tracking

如果用户会在多个子域之间穿梭，可以让匿名标识跟着走：

<script src="https://api.agentanalytics.sh/tracker.js"
  data-project="my-site"
  data-token="aat_..."
  data-link-domains="yoursite.com,app.yoursite.com,docs.yoursite.com"></script>

这对同时拥有 marketing site、docs 和 app 的产品特别有用。

隐私与 Do Not Track

tracker 现在也更好地尊重隐私偏好：

<script src="https://api.agentanalytics.sh/tracker.js"
  data-project="my-site"
  data-token="aat_..."
  data-do-not-track="true"></script>

用户也可以通过下面的方式本地关闭 tracking：

localStorage.setItem('aa_disabled', 'true');

Performance Timing

要采集页面性能指标，只需要：

<script src="https://api.agentanalytics.sh/tracker.js"
  data-project="my-site"
  data-token="aat_..."
  data-track-performance="true"></script>

系统会发送 $performance 事件，包含 TTFB、DOM interactive、完整加载时间等数据。

Time-on-Page

页面停留时长也可以自动采集：

<script src="https://api.agentanalytics.sh/tracker.js"
  data-project="my-site"
  data-token="aat_..."
  data-heartbeat="30"></script>

tracker 会在标签页隐藏时暂停、可见时继续，因此得到的是更接近真实 engagement 的时长。

JS Error Tracking

基础的 JavaScript 错误感知也内置了：

<script src="https://api.agentanalytics.sh/tracker.js"
  data-project="my-site"
  data-token="aat_..."
  data-track-errors="true"></script>

未捕获错误和未处理的 promise rejection 会作为 $error 发出来。

Global Properties

用 aa.set() 可以给后续事件统一附加上下文：

window.aa.set({ plan: 'pro', team: 'acme-corp' });
window.aa.set({ plan: null });

这对于按 plan、team 或 user type 分析特别有用。

Consent Management

对于需要先征得 consent 才能追踪的地区，也有内置支持：

<script src="https://api.agentanalytics.sh/tracker.js"
  data-project="my-site"
  data-token="aat_..."
  data-require-consent="true"></script>

然后你可以在 UI 中调用：

window.aa.grantConsent();
window.aa.revokeConsent();

Scroll Depth、Impression 和 Web Vitals

这次升级还包括：

• $scroll_depth，知道用户到底滚到了哪里
• data-aa-impression，知道某个区块是否真的进入可视区
• $web_vitals，采集 LCP、CLS 和 INP
• 自动文件下载追踪

这些能力让你看到的不只是“页面被打开了”，而是“用户真的看到了什么、体验到了什么”。

为什么这次升级重要

整体方向很明确：减少自定义埋点代码，让 measurement 更 declarative。

这对开发者有价值，对 AI 代理更有价值。因为代理最擅长的是改结构、补 attributes、运行工作流，而不是在每个页面里手写一层 tracking JS。

这也是我们做这次 Tracker.js 升级的核心原因。