Tracker.js

tracker.js 是 Agent Analytics 的浏览器端部分。适合用于页面浏览、自定义事件以及客户端实验，而无需引入一个很重的 SDK。

API 参考现在把 GET /tracker.js 仅视为脚本端点。安装和功能指南放在这里。

基础代码片段

在 </body> 前加入：

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

必填属性：

data-project：你的项目名称
data-token：公开项目令牌（aat_*）

跟踪器会自动发送一个初始 page_view，其中包含已清理的 URL 和 referrer、pathname、hostname、标题、屏幕尺寸、浏览器、操作系统、设备、语言、时区、session 次数、距首次访问天数，以及 allowlist 中的 UTM attribution。不需要 cookies。

隐私合同

Agent Analytics 会区分默认浏览器合同和显式 opt-in：

范围	默认行为	显式 opt-in
页面浏览	加载时发送一个初始 `page_view`。`url` 和 `referrer` 会清理为 `origin + pathname`；自动 URL 字段不会发送 query string 或 fragment。`path` 是当前 pathname。	SPA 路由监听需要 `data-track-spa="true"`。手动虚拟页面可以用 `aa.page(name)` 或 `aa.track('page_view', ...)` 发送。
Attribution	只从 query string 读取 `utm_source`、`utm_medium`、`utm_campaign`、`utm_content` 和 `utm_term`。它们会保留给当前 session 和 first touch。其他 query 参数不会被自动收集。	只有在安全且有意时，才用 `aa.track(...)` 自行添加自定义 campaign 字段。
浏览器字段	包含浏览器系列/版本、操作系统、粗粒度设备类型、语言、时区、hostname、标题和屏幕尺寸。跟踪器不会使用强 fingerprinting、动态脚本加载、`eval`、`document.write` 或表单值收集。	性能、Web Vitals、错误、滚动深度、404、下载、表单提交元数据、外链和通用点击默认关闭，直到设置对应的 `data-track-*` 属性。
点击和表单	声明式 `data-aa-event` 点击只发送事件名称和你显式添加的 `data-aa-event-*` 属性。	`data-track-clicks="true"` 会跟踪链接/按钮元数据，但不会发送可见点击文本。`data-track-forms="true"` 会跟踪表单元数据，但不会发送表单值。
身份	匿名 ID 和 session ID 会按项目 token/name 存放在浏览器存储中。旧的未限定作用域 key 不会被迁移，因此升级后可能会创建新的项目范围匿名 ID。	`aa.identify(userId, traits)` 只会在显式调用时发生。`userId` 请使用稳定的应用/账户 ID；只有当你希望支持场景按邮箱 lookup 时，才把邮箱作为顶层 `traits.email` 传入。
邮箱 lookup	邮箱不会被自动收集，也不应作为 `userId`。	当 `identify` 提供 `traits.email` 时，原始邮箱会通过 HTTPS 在这次 identify 调用中传输，以便服务端计算项目范围的 HMAC lookup 索引。原始邮箱默认会从 event rows 和 profile traits 中移除。
跨域身份	默认不会装饰链接。	`data-link-domains` 会用短暂的 `_aa` 匿名 ID 参数装饰允许的跨域链接，并在目标页移除它。
Consent 和 DNT	除非配置 consent 或 DNT，否则跟踪会立即开始。	`data-require-consent="true"` 会缓冲事件直到 `aa.grantConsent()`。`data-do-not-track="true"` 会遵循浏览器 DNT 信号。

到达跟踪器的自动化流量会从你的正常分析中被过滤掉。如果你想单独检查这些自动请求，请使用 Bot Traffic。

如果你的代理能修改代码，可以直接让它帮你添加代码片段。如果不能，请使用 5 分钟完成第一个项目来创建项目、拿到代码片段并验证第一个 page view。

常见选项

Attribute	作用
`data-link-domains="example.com"`	在同级域名或子域之间关联匿名身份
`data-do-not-track="true"`	遵循浏览器的 Do Not Track 信号
`data-heartbeat="15"`	在标签页可见时测量页面活跃时长
`data-track-outgoing="true"`	将外链点击记录为 `outgoing_link`
`data-track-clicks="true"`	将 `<a>` 和 `<button>` 点击记录为 `$click`
`data-track-errors="true"`	捕获未处理的 JS 错误和 promise rejection，并记录为 `$error`
`data-track-performance="true"`	为 `page_view` 添加 Navigation Timing 指标
`data-track-vitals="true"`	为 `page_view` 添加 Core Web Vitals
`data-track-downloads="true"`	将下载链接点击记录为 `$download`
`data-track-forms="true"`	将表单提交记录为 `$form_submit`
`data-track-404="true"`	将 404 页面记录为 `$404`
`data-track-scroll-depth="true"`	为 `page_view` 添加最大滚动深度
`data-track-spa="true"`	监听客户端路由变化并发送 route-change `page_view` 事件
`data-require-consent="true"`	在获得 consent 前先缓冲事件

示例：

<script defer src="https://api.agentanalytics.sh/tracker.js"
        data-project="my-site"
        data-token="aat_..."
        data-track-outgoing="true"
        data-track-performance="true"
        data-track-vitals="true"
        data-track-errors="true"
        data-track-scroll-depth="true"
        data-heartbeat="15"></script>

声明式事件

对于简单点击跟踪，通常不需要写自定义 JavaScript。你可以直接在 HTML 中加入 data-aa-event：

<button data-aa-event="signup_cta_clicked" data-aa-event-plan="pro">
  Sign up for Pro
</button>

这会发送一个 signup_cta_clicked 事件，并带上 { plan: "pro" }。

这通常也是代理最容易处理的方式。它们可以给现有标记加属性，而不用去接 onclick handler 或修改应用代码。

请把 signup 保留给账户真正创建完成的那个稳定时刻。如果按钮只是启动流程，请使用 signup_started 或 signup_cta_clicked 这样的中间事件，而不要把这次点击本身当成完成注册。

曝光跟踪

如果你想知道某个区块是否真的被看到：

<section data-aa-impression="pricing_table"
         data-aa-impression-plan="pro">
  ...
</section>

当元素进入可见区域时，跟踪器会发送一个 $impression 事件。

`window.aa` API

当事件依赖运行时状态时，请使用 JavaScript API：

window.aa?.track('checkout_started', { plan: 'pro' });
window.aa?.identify('user_123', { email: '[email protected]', plan: 'pro' });
window.aa?.set({ plan: 'pro', team: 'acme' });

常用方法：

aa.track(event, properties)：发送自定义事件
aa.page(name)：手动发送 page view
aa.identify(id, traits)：把匿名行为关联到稳定的已知用户 ID，并更新用于支持场景的私有 profile lookup 索引
aa.set(properties)：为后续事件附加全局属性
aa.experiment(name, variants)：在客户端确定性分配实验版本
aa.grantConsent() / aa.revokeConsent()：管理 consent 模式

有账户体系的应用：`signup`、`login` 和 `identify`

对于有登录体系的应用，认证成功后的浏览器侧推荐写法是：

window.aa?.identify(account.id, {
  email: account.email,
  plan: account.plan,
  team: account.team,
});

请在认证成功后立刻调用 aa.identify(account.id, traits)，并且要早于任何其他登录后浏览器事件。这样当前浏览器中的匿名行为才能被提升到与你服务端一致的规范用户 ID 上。第一个参数请使用稳定的应用用户 ID、账户 ID 或成员 ID，不要使用邮箱地址。只有当你希望之后按邮箱做支持查询时，才把邮箱作为顶层 traits.email 传入。

当 traits.email 存在时，原始邮箱会在 identify 期间通过 HTTPS 传输给 Agent Analytics，用于在服务端计算项目/portfolio 范围内的 HMAC lookup 索引。原始邮箱默认不会存入 event rows 或 profile traits；浏览器端 SHA-256 邮箱哈希和 email_hash payload 不再属于公开 tracker 合同。

推荐的事件边界：

signup 只发送一次，并且发生在账户真正创建时。最佳位置通常是服务端的账户创建路径。
login 发生在已有账户完成认证时。这里也更适合放在服务端的认证回调或会话创建路径里。
对于账户创建之前的前置 UI 步骤，请使用 signup_started、signup_cta_clicked 或 checkout_started 这样的客户端事件。

这样分层之后，漏斗会更真实，浏览器事件和服务端认证事件也会落到同一个 user_id 上。

SPA 路由与虚拟页面

默认情况下，Agent Analytics 只发送初始 page view。自动 SPA 路由跟踪现在需要显式 opt-in，因为它会监听 URL 变化并 patch history.pushState() / history.replaceState()。

要启用自动路由变化 page view，请添加 data-track-spa="true"：

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

启用这个 opt-in 后，当浏览器 URL 通过 history.pushState()、history.replaceState()、popstate 或 hashchange 发生变化时，Agent Analytics 会发送 page_view。这覆盖了大多数客户端路由器，包括基于 hash 的 SPA。

如果 UI 发生变化，但 path、query string 和 hash 都没有变化，跟踪器不会去猜测是不是出现了一个新页面。这种情况下，需要你手动发送 page_view。

推荐实现顺序：

真实 URL 变化
Hash 路由
手动虚拟 page_view

当当前浏览器 URL 已经和你要标记的页面一致时，可以使用 aa.page(name)。它会发送一个带有 page 属性的 page_view，但 path 和 url 仍然来自当前浏览器地址。

对于真正没有 URL 变化的虚拟页面，请手动发送 page_view，并自行覆盖路由字段：

window.aa?.track('page_view', {
  page: 'Checkout Step 2',
  path: '/checkout/step-2',
  url: `${location.origin}/checkout/step-2`
});

不要把手动页面跟踪和 Agent Analytics 已经能自动跟踪的路由跳转叠加在同一次变化上，否则会重复计数。

如果你想用提示词驱动的方式来决定该用路由跟踪还是虚拟页面跟踪，请查看 SPA 与虚拟页面跟踪。

常见配方

跨域身份关联

当同一访客会在相关域名之间移动，并且你希望它们保留同一个匿名浏览器身份时，请使用 data-link-domains。

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

点击时，tracker 会给这些域名的链接加上一个短暂的 _aa 查询参数。目标站点的 tracker 会捕获这个匿名 ID，把它与目标浏览器中的匿名 ID 关联起来，然后从地址栏移除 _aa。

如果多个站点使用同一个项目 token，data-link-domains 就足够了。如果它们是不同的 Agent Analytics 项目，请把这些项目加入同一个 identity portfolio；否则链接会被装饰，但跨项目读取仍然保持项目隔离。CLI 设置见 Identity portfolios。

典型 portfolio 流程：

discovery.example.com -> example.com -> app.example.com

单个 portfolio 中多个独立项目的示例：

agent-analytics portfolios create growth-system \
  --name "Growth system" \
  --projects example.com,discovery.example.com

然后在每个参与的 surface 上包含同一组 portfolio 域名：

<script defer src="https://api.agentanalytics.sh/tracker.js"
        data-project="discovery-example"
        data-token="aat_..."
        data-link-domains="example.com,discovery.example.com,app.example.com"></script>

真实点击后，在目标项目中验证：

agent-analytics query example.com \
  --metrics event_count,unique_users \
  --filter '[{"field":"properties.referrer","op":"contains","value":"discovery.example.com"}]' \
  --days 1

预期结果：来自该浏览器的目标事件会解析为一个 unique_users，而不是在来源项目和目标项目之间拆散。

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

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

用户授予 consent 后，之前缓冲的事件会自动发送。如果缓冲区超过 100 个事件，tracker 会把它拆成多个 /track/batch 请求，每个请求最多 100 个事件。

实验

<h1 data-aa-experiment="hero_text"
    data-aa-variant-b="Try it free today!">
  Start your free trial
</h1>

如果你想查看完整的提示词优先工作流，包括如何通过代理创建、接入、QA 和读取实验结果，请使用 AI 代理实验跟踪。

本地开发

在 localhost 上，跟踪器会切换到开发模式，并把活动记录到浏览器控制台，而不是发送到生产环境。这样本地测试就不会污染真实分析数据。