统一事件追踪 API

概述

HagiCode 官网使用 51LA 作为当前埋点服务，但业务代码不应直接调用 LA.track()。

所有官网事件都必须先进入 repos/site/src/lib/analytics/ 下的统一追踪层，再由内部 51LA 适配器完成第三方调用。这样可以带来三点收益：

降低耦合：页面和组件只依赖内部 API，不依赖第三方全局对象。
便于扩展：未来替换埋点服务商时，只需要调整适配层。
便于治理：事件命名、接入位置和扩展流程可以统一审查。

API 合约

代码入口

官网事件追踪的核心文件位于：

repos/site/src/lib/analytics/events.ts：事件注册表与标准事件名
repos/site/src/lib/analytics/provider-51la.ts：唯一允许调用 LA.track() 的 51LA 适配器
repos/site/src/lib/analytics/tracker.ts：统一运行时、队列、声明式委托与 trackEvent() API

命令式调用

React 组件中，请通过 trackEvent() 发送事件：

import { WEBSITE_TRACKING_EVENTS } from '@/lib/analytics/events';
import { trackEvent } from '@/lib/analytics/tracker';

trackEvent(WEBSITE_TRACKING_EVENTS.openDesktopPage, {
  source: 'install-options-desktop',
});

适用场景：

React 按钮点击
下拉菜单项选择
需要根据条件动态决定事件名的交互

声明式调用

Astro 页面中的原生链接或按钮，优先使用 data-track-event 和可选的 data-track-source：

<a
  href={dockerComposeDocsUrl}
  data-track-event="open-container-deployment-guide"
  data-track-source="container-cta-primary"
>
  前往部署指南
</a>

统一运行时会在浏览器端委托处理这些元素，无需在页面中直接书写第三方埋点代码。

首批标准事件目录

事件名	触发位置	业务含义
`download-desktop`	首页/导航栏主安装按钮	用户希望安装或下载 Desktop
`open-desktop-page`	首页安装方式区 Desktop 卡片	用户进入 Desktop 产品页
`open-container-page`	首页安装方式区 Container 卡片、安装按钮容器跳转	用户进入 Container 产品页
`download-desktop-windows`	Desktop 页面或安装按钮中的 Windows 下载项	用户下载 Windows 版本
`download-desktop-macos`	Desktop 页面或安装按钮中的 macOS 下载项	用户下载 macOS 版本
`download-desktop-linux`	Desktop 页面或安装按钮中的 Linux 下载项	用户下载 Linux 版本
`open-container-deployment-guide`	Container 页面部署指南入口、FAQ 文档链接	用户查看容器部署文档
`open-container-source-repo`	Container 页面 GitHub CTA	用户查看容器相关源码仓库

提示：文档中的事件目录必须与 repos/site/src/lib/analytics/events.ts 保持同步。新增、删除或重命名事件时，请在同一个变更里同时更新代码和文档。

禁止事项

以下做法应避免：

在页面、组件或 MDX 中直接写 LA.track('xxx')
在多个文件里随意发明新的事件名而不登记到注册表
为同一业务动作创建多个语义重复的事件名
让埋点失败阻塞下载、跳转或页面交互

命名规范

事件名使用 kebab-case，建议遵循以下原则：

先表达用户意图，再表达目标对象，如 open-desktop-page
对下载类事件，按平台维度区分，如 download-desktop-windows
尽量保持稳定，避免把文案、按钮样式或实验分组写进事件名
如果只是来源不同，优先通过 data-track-source 或上下文字段区分，而不是新增新事件名

新增事件清单

当你要新增、重命名或扩展事件时，请按下面的顺序处理：

在 repos/site/src/lib/analytics/events.ts 中新增或调整标准事件名
评估事件应该走命令式 trackEvent()，还是声明式 data-track-event
在目标页面或组件中接入统一追踪 API
确认第三方调用仍然只存在于 provider-51la.ts
更新本文档中的事件目录、示例和说明
运行站点验证，确认交互不受影响且事件名未漂移

设计约束

统一追踪系统还包含两个重要保护：

SDK 未就绪队列：如果 51LA SDK 还未可用，事件会先进入轻量队列，稍后再补发
静默降级：如果 SDK 加载失败，页面交互仍会继续执行，不应抛出前端错误

这意味着埋点是辅助能力，而不是阻塞主流程的前置条件。