Intlayer Analytics 文档

@intlayer/analytics 是一个可选的配套包，它可以告诉您哪些内容实际显示给了您的访问者 —— 哪个页面、哪个区域设置（locale）以及哪个特定的翻译内容片段 —— 从而让您能够了解您的受众并对内容运行 A/B 测试。

目录

跟踪内容

@intlayer/analytics 会批处理三种类型的匿名事件：

事件收集在内存中，并作为大约每 20 秒一次的单一批量请求发送 —— 而不是在每次击键或渲染时发送 —— 因此分析功能永远不会影响首次渲染时间，也不会在每次交互时增加网络请求。

它如何为内容的 A/B 测试提供支持

Intlayer 已经允许您声明内容 变体 (Variants)（例如，一个具有 control 和 black_friday 变体的 hero-banner 字典）。@intlayer/analytics 完成了整个循环：

1. getVariant(experimentKey, variants) 确定性地将每个匿名会话分配给一个变体 —— 它是会话 ID 和实验键 (experiment key) 的纯函数，因此分配在整个会话期间保持稳定，并且在首次渲染之前不需要服务器往返（无闪烁，无布局偏移）。
2. 每个 content_exposure 事件都会携带所显示的 variant。
3. useConversion() 允许您将目标（例如 "cta_click"）归因于该变体。
4. 仪表板的实验结果端点 (endpoint) 比较各变体的转化率，包括统计显著性（z 检验）。

安装

@intlayer/analytics 是一个对等 (peer)、可选的依赖项 —— 框架包永远不会自动安装它。请将其与 intlayer 一起添加：

npm install @intlayer/analytics

如果您不安装它，每个集成点都将解析为空操作 (no-op) —— 请参阅下文的未安装时零成本。

配置

Analytics 重用了现有的 editor 配置块 —— 没有单独的 analytics 配置模式需要填写：

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  editor: {
    backendURL: "https://back.intlayer.org", // 也用作分析数据摄取端点
    clientId: "your-client-id", // 也用作分析项目密钥
    clientSecret: "your-client-secret",
  },
};

export default config;

• editor.backendURL — 发送分析事件的基本 URL (POST {backendURL}/api/analytics/events)。
• editor.clientId — 归因于每个摄取事件的公共项目密钥。它也充当启用开关：在配置 clientId 之前，分析将保持完全禁用（并被摇树优化去除，见下文）。

如果您自托管 Intlayer，分析会自动指向您自己的实例，因为它共享 editor.backendURL。

框架支持

Analytics 已连接到 react-intlayer 共享的 IntlayerProvider 中，因此今天只要使用该 provider 的任何地方都可以使用它：

使用方法

自动 Provider 级别跟踪

无需更改代码。一旦安装了 @intlayer/analytics 并配置了 editor.clientId，IntlayerProvider 会自动：

• 在挂载时初始化分析客户端，
• 在初始加载时记录一个 page_view，
• 在每次更改区域设置时记录一个 page_view，
• 启动约 20 秒的刷新循环，并在卸载/关闭选项卡时刷新任何剩余事件（通过 navigator.sendBeacon，回退至 fetch(..., { keepalive: true })）。

自动 Node 级别跟踪

每次 useIntlayer 解析用于显示的内容片段时，解释器都会为该确切的 dictionaryKey + 键路径 + 区域设置报告一个 content_exposure 事件 —— 同样，无需更改代码。在刷新窗口内同一节点的重复曝光会合并为一个带有 count（计数）的事件，因此重新渲染 50 次的列表不会发送 50 个事件。

跟踪 A/B 测试的转化

使用 useConversion() 将目标归因于会话看到的变体：

在客户端解析变体

隐私与性能

• 设计上匿名：会话由轮换 ID 标识；后端永远只存储该 ID 的 SHA-256 哈希值 —— 从不存储原始 ID，从不存储 IP 地址。
• 位置是粗略的：只有一个国家/地区代码，该代码从 CDN 地理位置标头（cf-ipcountry、x-vercel-ip-country 等）派生 —— 不会读取或存储 IP。
• 默认情况下 URL 排除搜索参数，因此永远不会捕获查询字符串。
• 采样：sampleRate 允许您在高流量应用程序中仅保留一小部分内容曝光事件。
• 批处理：大约每 20 秒发送一个请求 (flushInterval)，或者如果缓冲区满了则提前发送 (maxBufferSize) —— 永远不会每个事件发送一个请求。

未安装时零成本

@intlayer/analytics 遵循与 @intlayer/editor 完全相同的可选依赖模式：

• 每个集成点通过包裹在 try/catch 中的动态 import() 加载包 —— 从未安装 @intlayer/analytics 的应用程序永远不会支付包大小或运行时成本，也永远不会看到错误；
• 一个编译时环境变量（INTLAYER_ANALYTICS_ENABLED），当没有配置 editor.clientId 时，它会由 @intlayer/config 自动设置为 'false'，允许打包器 (bundlers) 将整个集成作为死代码消除 (dead-code-eliminate)；
• 分析在 Intlayer 编辑器/CMS 预览 iframe 中被禁用，因此编辑器会话永远不会算作真实流量。

仪表板：Analytics 页面

一旦您的项目收集了事件，Intlayer 仪表板 中的 Analytics（分析） 页面（选择项目后在侧边栏中可见）会显示：

• 活跃用户 — 选定滚动窗口（7 / 30 / 90 天）内的独立访客。
• 今日用户 和 过去 7 天的用户。
• 选定窗口内的 页面浏览量。
• 每日独立访客的 演变图。
• 区域设置 (Locales) 和 位置 (Location) 细分选项卡，按区域设置和国家/地区对您的受众进行排名。

后端 API 参考

所有读取端点都需要身份验证；数据摄取是公开的，并且由主体中的 clientId 进行归因。

您还可以使用 CMS SDK 以编程方式调用这些端点：

import { createIntlayerCMS } from "@intlayer/api";import { analyticsEndpoint } from "@intlayer/api/analytics";const cms = createIntlayerCMS();const { data: audience } = await analyticsEndpoint(cms).getAudience(30);

有用的链接

• 动态字典 - 集合与变体 (Collections & Variants)
• Intlayer CMS - CMS SDK
• Intlayer 可视化编辑器
• 配置参考
• 自托管指南