测量如何运作
文档分析通常会以同样的四种方式产生误导：将爬虫计为读者，将后台标签页计为阅读，将所有者自己的访问计为受众，以及基于少量访问次数引用百分比。本页详细说明了其工作机制，便于你在依据某个数据采取行动之前，亲自核查这些问题。
您将获得什么#
Docsbook 分析面板中的每个图表都源自同一个事件流，
基于同一套访问定义和同一套人类定义，而不是来自一组可能彼此不一致的独立计数器。当一个数字无法被如实表达时，您看到的会是破折号、“未测量”标签或被抑制的百分比，绝不会是一个自信的 0。而且，为了生成这些数据，不会在读者的浏览器中存储任何内容。
收集了什么，以及有意不收集什么#
Docsbook 会在您的文档网站上记录36 个命名的 docs.* 事件 — 页面
浏览、阅读时长片段、滚动进入视图的标题、搜索、AI 聊天
操作、复制、导航点击、外部链接点击、反馈投票和退出。
完整列表请参阅已跟踪事件参考。
每个事件都会携带其所属的项目、页面路径，以及以下适用的信息：秒数、标题锚点、引荐来源、目标主机、语言、 User-Agent，以及边缘节点根据请求解析出的国家/地区/城市/坐标。读者的 IP 会在 服务器端的接收端点附加，绝不会由浏览器附加。
| 不收集的内容 | 原因 |
|---|---|
Cookie、localStorage 或任何用于分析的浏览器端标识符 |
统计访问者无需在其设备上存储任何内容，因此不会存储 |
| 跨站点或跨项目身份 | 访问者哈希使用您项目自身的名称加盐，因此同一 IP 在两个 Docsbook 网站上会生成两个互不相关的 ID |
| 设备指纹识别（画布、字体、音频） | 跟踪器中的任何位置都未实现此功能 |
| 表单输入、按键记录、会话回放、鼠标轨迹 | 不存在此类收集器 |
| 任何报告、导出内容或 MCP 响应中的原始 IP | IP 保留在事件存储中；下游所有部分看到的都是哈希值 |
| 泄露到事件中的机密信息 | 原始事件读取会经过脱敏器，它会屏蔽键名或值看起来像令牌、密钥、JWT 或授权标头的任何字段 |
访客和访问的定义#
访客是 sha256(secret salt + project + IP)，截断为 16 个十六进制
字符。 这就是完整的身份标识。它是稳定的——同一个人在下周访问时会获得相同的标识符——同时也是限定范围的：盐值是服务器端的机密，项目名称也是输入的一部分，因此该 ID 无法与任何其他网站的流量关联，包括另一个 Docsbook 项目。
访问是根据事件重建的，而不是通过会话 Cookie 进行跟踪。 同一访客的事件会按时间排序，并在间隔超过 30 分钟 的位置进行切分。这是一个非活动间隔，而不是固定的时钟分桶，这是有意为之的：分桶会将跨越边界的一次访问拆分开来，因此，一个从 12:29 活跃到 12:31 的读者会被错误地报告为两次访问。
机器人和爬虫如何被过滤#
过滤分为两个独立层，因为已知单独依靠其中任何一层都会失败。
- User-Agent。 一个涵盖爬虫、蜘蛛、无头浏览器、脚本化 HTTP 客户端、SEO 套件和链接预览抓取器的正则表达式，以及分类器表中的每个 AI 机器人。两个字面量 UA 字符串被固定加入，因为观察到它们以较大规模进行爬取，却声称自己是普通手机——一个 Googlebot Smartphone 参考设备和一个过时的 iOS 版本。
- 行为。 一次访问没有产生任何只有 JavaScript 运行时才能发出的事件——没有阅读时长分段、没有标题查看、没有退出、没有点击——这说明它没有运行 JavaScript，无论其 User-Agent 声称是什么，它都是爬虫。
除此之外，您自己的团队会从所有读者数据中排除。 如果某位访客的 IP 在过去 30 天内还为此项目发送过管理员会话信标，则会被标记为所有者，并从读者指标中剔除——与机器人标记分开处理，因为他们是真实的人，只是不是您的受众。还可以选择使用服务器端 IP 允许列表，在内部流量被写入之前将其丢弃。
机器人和所有者的访问会被保留并标记，而不是删除，这样面板可以向您显示区分结果，而不是悄悄缩减您的数字。
阅读时长实际上是如何计算的#
跟踪器会在页面挂载时开始计时，并在读者离开时读取时长——在 pagehide、iOS 上的 visibilitychange → hidden（此时 pagehide 不可靠），以及站内导航时都会读取。每次读取都会发出一个 docs.read_time 片段并重置计时器，因此返回某个页面时会产生两个片段，而不是一段被重复计算的时长。短于3 秒的片段完全不会发出。
数据通过 navigator.sendBeacon 发送到同源端点，每个信标最多批量发送 100 个事件。普通日志传输会通过 fetch 防抖两秒，而这种方式无法在标签页关闭后保留数据——阅读时长、标题查看和离开是必须在标签页关闭后仍然保留的事件，因此它们会改走信标路径。
然后，每个片段都会在进行任何求和之前截取为最多 300 秒。这是本页最重要的单个数字。桌面标签页在后台停留时，发射器仍会持续计时；在对 7 个工作区中的 11,176 个真实会话进行扫描时，有 40 个独立片段超过了两小时，第 99 百分位为 81,342 秒，而对原始片段求和会使总阅读时长膨胀约三十倍——截取前为 1,268,422 秒，截取后为 42,160 秒。所有引用时间数据的界面都会应用同样的截取规则，因此面板、每页列、目标层和 MCP 工具不会出现不一致。
每页平均阅读时长是用截取后的总时长除以片段数，而不是访问次数：读者离开标签页后又返回，会在一次访问中贡献两个片段；按访问次数取平均会让这次访问被计算两次。
如何区分 AI 助手流量与人类流量#
请求会被分类为三个永不合并的组：
| 组 | 示例代理 | 这对你意味着什么 |
|---|---|---|
| 回答 — 当前正在回答某个人 | ChatGPT-User, Perplexity-User, Claude-Web, DuckAssistBot |
你的页面被引用给某个人。这是有价值的流量，通常不会带有引荐来源 |
| 索引 — 构建助手检索所依据的语料库 | OAI-SearchBot, PerplexityBot, Bingbot, Applebot, GoogleOther |
这是未来能够被引用的前提 |
| 训练 — 批量收集 | GPTBot, ClaudeBot, CCBot, Google-Extended, Bytespider |
只支持一个决定：是否允许它 |
无法识别的 AI 机器人名称会被视为训练 — 这是对你承诺最少的分类。分类依据是 User-Agent，按照先匹配者优先的顺序进行，因此
Applebot-Extended 永远不会被 Applebot 吞掉。
采样、上限和保留期限#
不存在采样。 面板中的任何数字都不是根据部分流量外推得出的。实际存在的是一个硬性上限：会话重建每个窗口最多读取 50,000 个事件，达到该上限时，结果会带有
truncated 标志，使用者必须将其显示出来，因为基于截断窗口计算的比率是不正确的。查询如果失败，也会被报告为失败，而不是报告为零——空的仪表板和读取故障是不同的结果。
所有方案都会保留读取事件 30 天。 三十天是数据的截止时间，而不是某个层级的限制：这是事件存储的保留期限。产品中的每个时间段选择器都读取同一个常量，因此任何控件都不会提供数据无法填满的时间窗口。AI 使用情况账本存储在单独的存储中，保留时间更长——90 天，每日清理——因此即使报告不再显示相关内容，仍可在有争议的账单发生后重建记录；无论如何，任何报告提供的时间范围都不会超过 30 天。
数据存储在哪里#
| 数据 | 位置 | 保留时间 |
|---|---|---|
docs.* 读取器事件，包括生成哈希的原始 IP |
Axiom，第三方事件数据仓库 | 30 天 |
| 目标、漏斗及其定义；AI 和 MCP 计费账本；工作区设置 | Docsbook 自有的 Postgres 数据库 | 目标和漏斗在归档前一直保留；AI 账本保留 90 天，每日清理；MCP 调用记录目前不会清理 |
| 聊天回答评定结果 | Docsbook 的 Postgres 数据库，每次对话写入一次 | 与对话一同保留 |
面板中显示的 Search Console 数据是根据您授权的连接从 Google 获取的， 这些数据属于 Google，而非 Docsbook。
隐私与 GDPR——哪些是技术事实，哪些由您决定#
可通过网站行为验证的技术事实：
- Docsbook 的文档站点分析功能不会向读者的设备写入任何内容，也不会从设备读取任何内容。不存在分析 Cookie，也不存在存储在浏览器中的 ID。
- 读者身份通过密钥哈希从 IP 地址派生，并在服务器端按您的项目进行限定。该哈希是单向的；任何报告、导出或 MCP 工具都不会暴露原始 IP。
- 不同项目之间不会共享任何标识符，也不会出售、联合提供或用于构建跨站点用户档案。
- 数据保留期限为 30 天，由存储系统强制执行，而不是通过报告筛选器实现。
我们不作出的声明。 Docsbook 不声称运行它就能使您的网站无需征得同意、符合 GDPR，或不受任何国家法规约束。以下两点必须由您自己的法律顾问决定：
- 电子隐私同意规则是否适用。《指令 2002/58/EC》第 5(3) 条（经修订）规定，“在终端设备中存储信息，或获取对已存储信息的访问权限”须以同意为条件。Docsbook 不会在设备上存储或读取任何内容，而该条款所指的触发条件正是这一行为——但 EDPB 的《关于第 5(3) 条技术范围的指南 2/2023》专门设有“仅基于 IP 的跟踪”一节，因此应将“没有 Cookie，所以无需同意”视为一种论据，而非确定结论。
- 您是否仍需依据 GDPR 确立合法处理依据。无论 Cookie 问题如何，能够识别读者的 IP 地址都属于个人数据，因此您的隐私声明、处理依据以及与上述供应商签订的处理者条款，均由您自行确定。CNIL 针对受众测量的豁免标准可作为这里的实用检查清单；Docsbook 满足其中若干项（单一发布者、不进行跨站点关联、目的仅限于受众测量），但并非全部满足——尤其是，它不会在存储 IP 之前截去 IP 地址的最后一个字节。
为什么这是正确的做法#
| 规则 | 原因 | 来源 |
|---|---|---|
| 阅读时间必须进行截取，而不是直接累加 | 之所以存在页面可见性规范，是因为“网页开发者一直按照页面始终可见的情况来设计网页”——页面在隐藏时仍持续计时，正是这种错误 | W3C 页面可见性 Level 2 |
| 严肃的分析会将参与度定义为前台时间 | Google Analytics 4 将其定义为“某人在聚焦于您的网页时所花费的时间”——截取时间是我们对相同意图的近似，并且这一点是明确说明的，而非隐含的 | GA4：用户参与度 |
退出时事件必须通过 beacon 发送，而不是 fetch |
Beacon 请求“保证会在页面卸载前启动，并且允许运行至完成” | W3C Beacon API |
监听 pagehide，而不是 unload |
unload“仍然不可靠，因此除非绝对必要，否则应避免使用”；pagehide“会在所有触发 unload 事件的情况下触发”，并且还会在进入 bfcache 时触发 |
web.dev：bfcache |
| User-Agent 是一种声明，而非身份 | Google 发布爬虫验证指南，正是因为存在“声称来自 Google 的垃圾信息发送者或其他捣乱者”——因此需要增加第二个行为层 | Google 搜索中心：验证 Googlebot |
| “回答”、“索引”和“训练”代表三种不同的访问者 | OpenAI 发布了三个独立的代理：GPTBot 可能会“抓取可能用于训练的内容”，OAI-SearchBot 的存在是“为了在搜索结果中展示网站”，而“ChatGPT-User 不会以自动方式用于抓取网络内容”。Perplexity 也作出了相同区分：PerplexityBot“不用于为 AI 基础模型抓取内容” | OpenAI 机器人、Perplexity 机器人 |
| 衡量访问是否成功，而不是访问了多少个页面 | “如果用户无法完成其目标任务，其他一切都无关紧要”（Nielsen & Budiu，2001 年，2021 年复审） | NN/g：成功率 |
| 分析同意是一项法律判断，而非产品设置 | 第 5(3) 条涉及“在终端设备中存储信息，或获取对已存储信息的访问权限”；法国国家信息与自由委员会的豁免标准还增加了第一方范围、用途限制和 IP 截断等要求 | 《电子隐私指令》合并版、CNIL 第 16 号说明 |
局限性与未解问题#
- 每个访客数都是估算值，产品在其自身的响应中也明确说明了这一点。经过哈希处理的 IP 会将同一企业 NAT 后的所有人合并为一个读者，也会将同一名通勤者拆分为多个读者。应将访客数据视为趋势；切勿将其引用为实际人数。
- 阅读时长会被截断，而不是以可见性为依据进行计时。在桌面设备上，留在后台打开的标签页会持续累加秒数，直到达到 300 秒的截断上限。这诚实地反映了其误差方向——阅读时长存在向上的偏差，并且有上限——但它并不等同于 GA4 基于焦点的互动时长，本说明也没有声称二者相同。
- 机器人过滤器属于启发式方法，没有验证步骤。Docsbook 不会对爬虫声称的身份执行反向 DNS 或已公布 IP 范围检查，因此会直接按照 User-Agent 的表面值进行分类。行为层可以捕获 UA 正则表达式遗漏的常见情况；但这两个层面都不是安全控制措施。
- 所有者排除依赖于一次信标请求。一名查看文档、但在过去 30 天内从该 IP 从未打开过管理面板的队友，会被计为读者。
- Geo-IP 解析的是网络，而不是个人。企业 VPN 会将读者定位到隧道终止所在的城市；移动网络的定位可能偏差一百公里。
- 仍待解答：“无 Cookie”并不等同于“无需征得同意”。可以验证的是，Docsbook 文档站点的分析功能不会在浏览器中存储或读取任何内容，并且读者身份是经过加盐处理的服务器端哈希值。尚未确定的是其法律后果：EDPB 已明确提出 Art. 5(3) 下仅基于 IP 的跟踪问题，而没有任何公开来源能够针对哈希化、第一方、30 天这一情形给出结论。合规结论应由你的法律顾问作出。
- 三十天是硬性上限。仅凭这些数据，根本无法进行同比分析、季节性阅读分析，也无法分析超过四周的群组。