Analytics

关键实现注意事项

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

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全局变量。

切勿在自定义事件中跟踪PII（电子邮件、姓名、IP）。这违反了隐私原则。

通过批处理PostHog事件via/batch端点。Umami/Plausible 需要逐个请求处理。

认证模式

将API密钥存储在环境变量中仅此而已。切勿硬编码。

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

Plausible：使用Bearer令牌认证。

PostHog：使用项目特定的API密钥。