Velt View Analytics Best Practices 是针对 Velt View Analytics 功能的实现指南。该功能是一个“今天谁查看了这份文档”的指示器，包含触发器徽章、最近浏览者对话框（桌面端）和底部弹层（移动端），并提供可观察对象与 hook API，用于按用户或按日期聚合浏览数据。
适用场景 在以下情况应参考这些指南：
在工具栏中放置 <VeltViewAnalytics>（或 <velt-view-analytics>）时； 使用 type="location" + location-id 将范围限定到子文档时； 从 React（useUniqueViewsByUser、useUniqueViewsByDate hooks）或非 React（client.getViewsElement().get*().subscribe(...)）代码读取唯一浏览计数时； 使用线框标签（<velt-view-analytics-wireframe>、<velt-view-analytics-dialog-wireframe>、<velt-view-analytics-bottom-sheet-wireframe>）构建完全自定义的触发器徽章或浏览者列表时； 读取 componentConfig.* 模板变量（todayViewsCount、totalUniqueViewsCount、treadsVisible、userViews、bottomSheetMode 等）时。
关于通用 SDK 设置（VeltProvider、身份验证和文档标识），请参阅 velt-setup-best-practices。
命名注意事项 — getViewsElement（复数） 元素句柄是 client.getViewsElement()（复数），而不是 getViewElement（单数）。调用 getViewElement() 是基础模型常见的幻觉，它并不存在。复数形式与 hook/observable 名称（getUniqueViewsByUser、getUniqueViewsByDate）保持一致。
treadsVisible（有意为之的拼写） 表示“对话框已打开”的线框变量名是 componentConfig.treadsVisible——拼写为 treads（不是 threads）。这是 SDK 侧的遗留拼写；使用 threadsVisible 会静默返回 undefined。对话框打开/关闭样式应绑定到 treadsVisible。
按优先级划分的规则类别
- API（高影响，前缀 api-）
- 线框变量（中影响，前缀 wireframe-variables-）
快速参考 API（高） api-setup——<VeltViewAnalytics> 的放置；用于位置限定触发器的 type="location" + location-id 属性。 api-views-subscriptions——React hooks（使用 useViewsElement 获取句柄；使用 useUniqueViewsByUser / useUniqueViewsByDate 获取数据）与非 React observable 形式（client.getViewsElement().get*().subscribe）；规范返回类型（Observable<ViewsByUser[]> / Observable<ViewsByDate[]>）；可选的 locationId 过滤器；订阅清理。
线框变量（中） wireframe-variables-view-analytics——三个线框标签（触发器 / 对话框 / 底部弹层）；每个作用域的完整 componentConfig.* 参考；treadsVisible 拼写；扁平配置访问模式（始终使用 componentConfig.<path>）。
使用方法 阅读各规则文件以获取详细说明和代码示例：
rules/shared/api/api-setup.md rules/shared/api/api-views-subscriptions.md rules/shared/wireframe-variables/wireframe-variables-view-analytics.md
每条规则包含： 为什么重要 React / Next.js 及其他框架代码示例 常见陷阱 验证清单 指向官方文档的来源指针
汇编文档 AGENTS.md——包含所有规则及文件路径的压缩索引（从这里开始）。 AGENTS.full.md——完整详细指南，内联展开所有规则。