快速开始

这是从零到可用 Agent Analytics 配置的最短路径。

主路径现在是 agent-first：先把 Agent Analytics 安装到你已经在用的代理里，让代理为你打开浏览器或给你一个登录链接，然后再让代理创建项目并接入跟踪。

如果你的代理已经安装好了，而且你想要一条最明确的创建项目、放入代码片段并验证第一个 page view 的完整引导，请使用 5 分钟完成第一个项目。

1. 选择并完成一条安装路径

前往安装中心，完成你实际使用环境对应的配置：

如果这些都不适合你，也可以直接使用 API 参考进行集成。

2. 在项目目录里打开你的代理

从你真正想跟踪的代码库或站点开始。

然后把下面这类请求交给代理：

Set up Agent Analytics for this project. Install it here if needed. Open the browser for me or send me the login link, then wait. I will sign in with Google or GitHub, approve it, and paste back any finish code if you need it. Then create the project, add tracking, and verify the first event.

当浏览器审批页打开时，就用 Google 或 GitHub 登录并批准，然后让代理继续。这个审批会创建或连接你的账户，并把代理所需的 session 交给它。

3. 创建你的第一个项目

连接好代理之后，让它帮你创建第一个项目：

Create a project called my-site.com
Create a project called my-site.com and give me the tracking snippet

如果你的代理有权写入网站代码，也可以直接让它：

Set up analytics for my-site.com

你的代理应该会创建项目，然后：

把跟踪代码片段返回给你手动粘贴，或者
如果它能修改网站代码，就直接帮你安装跟踪器

4. 如果需要，手动添加跟踪器

如果代理已经把跟踪器加到网站里了，可以跳过这一步。

如果它只是创建了项目并返回代码片段，请在 </body> 前加入下面这段脚本：

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

初始 page view 会自动跟踪。如果你的应用是 SPA，并且也希望自动跟踪路由变化，请在 script 标签上添加 data-track-spa="true"；否则请为虚拟屏幕发送有意的手动 page 调用。

自动 URL 字段默认是隐私安全的：url 和 referrer 会清理为 origin 加 pathname，自动 attribution 只读取 allowlist 中的 UTM key：utm_source、utm_medium、utm_campaign、utm_content 和 utm_term。后续你可以通过 data-aa-event 属性或 window.aa.track() 添加自定义事件。

如果你的产品有登录或注册，请把 signup 保留给账户真正创建的时刻，最好在服务端发送。浏览器认证成功后，只有当你有意希望按邮箱做支持 lookup 时，才调用 window.aa.identify(account.id, { email: account.email })。用户 ID 请使用稳定的应用/账户 ID，不要使用邮箱地址。Agent Analytics 会在服务端计算项目范围的 HMAC lookup，并默认从 event rows 和 profile traits 中移除原始邮箱。

浏览器存储会按项目 token/name 限定作用域。旧的未限定作用域匿名 ID 不会迁移，因此从旧 tracker 升级后，访客可能会获得新的项目范围匿名 ID。

如果你的网站使用 Astro，请给这段 tracker 标签加上 is:inline。

如果你需要声明式事件、跨域身份、consent、滚动深度、vitals 或错误跟踪等高级选项，请使用 Tracker.js 指南。如果你的应用是 SPA，请查看 SPA 与虚拟页面跟踪，在 data-track-spa="true" 路由跟踪和手动虚拟 page_view 调用之间做选择。如果你想在完成配置后让代理帮你启动第一个浏览器侧 A/B 测试，请继续阅读 AI 代理实验跟踪。

5. 验证闭环

当安装已生效、跟踪器也开始工作后，向你的代理发起这些查询之一：

List my projects
How is my-site doing this week?
What are the top pages for my-site this week?
Show bot traffic for my-site this week

如果配置正确，代理应该能直接回答，而不需要你手写 HTTP 请求。

高级 fallback：API 密钥

如果你需要为自己的运行时直接走 HTTP，也仍然可以在 app.agentanalytics.sh 里生成 API 密钥。这是高级/手动路径。CLI、MCP 和代理 onboarding 应该优先使用浏览器审批和 agent session。

下一步

使用安装获取针对不同代理的最快接入路径。
当你想要从代理已安装一直走到第一个真实项目上线的完整激活引导时，使用 5 分钟完成第一个项目。
当你的应用在客户端切换页面，并且你希望在不重复计数的前提下保持准确页面跟踪时，使用 SPA 与虚拟页面跟踪。
当你想让代理替你启动并读取浏览器侧实验时，使用 AI 代理实验跟踪。
使用 Tracker.js 查看浏览器端跟踪选项。
使用 Bot Traffic 检查从正常分析中被过滤掉的自动化流量。
使用 Authentication 理解读令牌与写令牌的区别。
使用 API Reference 查看端点级细节。