analyticsOS 追踪

analyticsOS 追踪 是做什么的？

analyticsOS 通过每个应用的一个脚本记录页面浏览、点击、滚动、表单、错误、加载速度和已登录用户。安装只需在页面 <head> 中添加两个标签；大部分工作是将它们放在适合技术栈的正确位置，并确保不包含个人数据。

你需要从用户那里获取的信息

analyticsOS 设置页面会为用户提供一个包含三个值的提示。询问所有缺失的值；切勿猜测。

• Host（主机）：analyticsOS 运行的主机地址，例如 https://analytics.example.com。
• Key（密钥）：应用的公钥，格式为 prj_…。它不是秘密：它会出现在加载脚本的每个页面中。
• Mode（模式）：Identified（需要登录、用户协议包含同意的应用）或 Anonymous（公共网站，不存储任何设备信息）。

安装

1. 确定技术栈并在进行任何更改前阅读对应的参考文档：

   • Next.js（App Router 或 Pages Router）：references/nextjs.md
   • Flask 或其他 Jinja 应用：references/flask.md
   • Webflow：references/webflow.md
   • 其他任何框架（纯 HTML、Vite、Astro、SvelteKit、Rails、Django、PHP、WordPress……）：references/any-site.md

2. 使用环境变量，而非硬编码的值：ANALYTICS_HOST 和 ANALYTICS_KEY，并根据构建工具要求加上适当的前缀（Next.js 使用 NEXT_PUBLIC_，Vite 使用 VITE_）。将它们放入本地 .env 文件中，将名称及其空值添加到 .env.example，并告知用户在托管平台设置中（Railway → Variables，Vercel → Environment Variables……）为每个需要运行追踪的环境设置这些变量。

3. 两个标签，放在每个页面的 <head> 中，且仅在设置了密钥时加载。 没有密钥时不得加载任何内容：这是本地开发和预览的开关。

   <script>
     window.aos =
       window.aos ||
       function () {
         ;(window.aos.q = window.aos.q || []).push(arguments)
       }
   </script>
   <script defer src="{ANALYTICS_HOST}/s/{ANALYTICS_KEY}.js"></script>
   

   第一个标签将脚本加载前的调用放入队列；第二个标签加载带有应用设置的脚本。

4. 已登录用户（仅 Identified 模式）：请参阅 references/events.md。在 Anonymous 模式下，不要添加身份识别调用，也不要存储访问者的任何信息。

5. 为主页面区块命名：在关键页面的元素上添加 data-section="Pricing"（如英雄区、定价、注册表单……），以便报表能识别它们；在任何不希望被读取文本的元素上添加 data-private，例如：客户姓名、金额、地址等任何个人信息。

6. Content-Security-Policy：如果项目设置了 CSP，则需要在 script-src 和 connect-src 中允许主机地址。

7. 不要做其他事情：不要添加其他分析工具、Cookie 或同意横幅。analyticsOS 不需要这些。

8. 完成：运行项目的构建和 lint，列出你修改过的文件，并告知用户在浏览器中打开应用。analyticsOS 设置页面会在几秒钟内标记出第一次页面浏览。

脚本已自动捕获的内容

以下内容无需编写代码，脚本会自动处理：

• 页面浏览，包括单页应用中的客户端导航；
• 对链接、按钮以及任何带有 data-aos-event 属性的元素的点击，包括站外链接、下载链接、狂点点击和无效点击；
• 滚动深度和页面停留时间；
• 表单的开始、提交和放弃（绝不会记录输入内容）；
• 核心 Web 指标（LCP、INP、CLS、FCP、TTFB）、JavaScript 错误以及失败的同源请求。

自定义事件、命名点击和身份识别相关请参阅 references/events.md。

隐私规则

无论用户提出什么要求，以下规则适用于所有项目：

• 绝不发送电子邮件地址、姓名、电话号码或用户输入的任何内容：不在 identify 的特征中，不在 track 的属性中，也不在 data-aos-event 的名称中。
• 使用应用内部用户 ID 进行身份识别，绝不使用电子邮件。
• 为显示个人数据的元素添加 data-private 标记。脚本也不会读取输入框、文本区域或 contenteditable 属性的内容。
• 发送 Do Not Track 或 Global Privacy Control 的浏览器将完全不进行追踪，并且 aos() 调用将被忽略。不要试图绕过这些设置。

当数据未到达时

打开应用的浏览器网络标签：

• /s/{key}.js 应成功加载（200），随后对 {host}/api/e 的请求应返回 204。
• 来自 /api/e 的 403 错误：页面的域名不在应用的允许域名列表中（analyticsOS → 应用设置）。添加该域名，或者在测试期间将列表留空。
• 404 错误：密钥错误或超过 24 小时未轮换。
• 完全没有请求：该环境中未设置密钥变量，Content-Security-Policy 阻止了主机，或者浏览器发送了 Do Not Track / Global Privacy Control。
• Next.js 中，事件在第一个页面后停止：标签作为普通 <script> 元素添加到了嵌套布局中。请使用 next/script 在根布局中添加（参见 references/nextjs.md）。