Analytics

关键实现注意事项

Umami API 时间戳：使用毫秒，而非秒。JavaScript 中使用 Date.now()，Python 中使用 int(time.time() * 1000)。

Plausible API v2：需要 site_id 参数，而非域名。请先从仪表盘 URL 获取 site_id。

PostHog 事件：属性必须为可序列化的 JSON 格式。切勿传递 DOM 元素或函数。

请求频率限制：Umami 600 次/小时，Plausible 600 次/小时，PostHog 1000 次/分钟。遇到 429 错误时，应实现指数退避机制。

环境特定配置

开发环境：本地测试时务必使用独立的项目/站点。生产数据污染无法逆转。

跟踪域名：切勿硬编码。使用环境变量在 localhost 与生产环境间切换。

机器人过滤：在设置中启用。隐私优先工具的机器人检测能力弱于 Google Analytics。

GDPR 合规注意事项

欧盟访问者需明确同意，即使使用隐私优先工具也需如此。追踪前请检查 IP 地理位置。

数据保留：设置自动删除策略——Umami 在“设置 > 数据”中配置，Plausible 最多保留 30 天，PostHog 在项目设置中配置。

无 Cookie 提示：Umami/Plausible 虽不使用 Cookie，但若收集标识符，仍需为欧盟访问者获取同意。

运行时安全

验证脚本加载：发送事件前检查 umami、plausible 或 posthog 全局变量是否存在。

绝不追踪个人身份信息（如邮箱、姓名、IP）于自定义事件中。违反隐私原则。

批量发送 PostHog 事件：通过 /batch 接口。Umami/Plausible 需要单独请求。

认证模式

API 密钥仅存储于环境变量中。切勿硬编码。

Umami：需要网站 ID 与 API 密钥组合。

Plausible：使用 Bearer Token 认证。

PostHog：使用项目专属 API 密钥。