添加统计分析与客服聊天
在所有页面加载 Google Analytics、Umami、Plausible、Clarity 或 Crisp 聊天组件,检查连接,并按国家查看统计。
在管理后台保存服务商的标识后,它的脚本会在所有页面加载。再保存 API 凭据,就能拉取报表确认连接。所有服务商都是可选的,彼此独立,都不读取环境变量。
准备工作
- 在要使用的服务商为自己的域名创建好站点或项目。
- 具备
config.write的管理员账号。只有config.read可以打开页面,但不能保存、拉取报表或上报测试事件。 - 按国家查看统计需要
countries.read。
每个服务商分两部分:公开标识用于加载脚本,API 凭据只在管理员拉取报表时使用。
| 服务商 | 用途 | 加载脚本所需 | 拉取报表所需 |
|---|---|---|---|
| Google Analytics | 在 GA4 中查看访问和事件 | Google Analytics ID | GA Property ID 和 GA Data API Access Token |
| Google Ads | 为 Ads 账号加载 Google 代码 | Google Ads ID | 不拉取 |
| Umami | 注重隐私的访问统计,云服务或自托管 | Umami Website ID | Umami API Key |
| Plausible | 注重隐私的访问统计,云服务或自托管 | Plausible Domain | Plausible API Key |
| Microsoft Clarity | 热力图和会话录屏 | Clarity Project ID | Clarity API Token |
| Crisp | 在线客服聊天组件 | Crisp Website ID | 不拉取 |
在分析服务商创建站点
| 厂商 | 适用场景 |
|---|---|
| Google Analytics | GA4 网页访问与报表 |
| Google Ads | 加载广告标签并配置转化标签 |
| Umami | 云端或自托管访问统计 |
| Plausible | 基于站点域名的流量统计 |
| Microsoft Clarity | 热力图和访问录屏 |
| Crisp | 嵌入在线客服组件 |
接入服务商
打开分析配置
进入 设置 → 分析配置(/admin/config/analytics)。表单按服务商分为 Google、Umami、Plausible 和 Clarity / Crisp 几块,运行检查 面板显示每个服务商的标识是否已保存。
填写服务商字段
按上方对应厂商指南中的字段对照表填写。
Token 和 API Key 字段保存后不会再显示,占位文字为 留空则保留当前 token。清空某个标识会移除该服务商的脚本,清空 Base URL 或 Script URL 会恢复默认值。
保存
点击 保存分析配置。页面提示 Analytics provider 配置已保存。,运行检查 面板随之刷新。
没有同意弹窗
保存后,每个已配置的脚本从下一次页面加载起在站点所有页面加载,包括管理后台。系统没有 Cookie 同意弹窗,也没有按页面开关。如果业务要求先征得访客同意再统计,请在启用服务商之前自行加上同意流程。
拉取服务商报表
拉取
在 分析配置 的 供应商报表 卡片中点击 拉取报表。
查看结果
Google Analytics、Umami、Plausible 和 Clarity 各自显示 通过 并附返回行数、失败 并附服务商返回的 HTTP 状态,或 未配置 并说明缺少哪些字段。只有标识和 API 凭据都已保存,才会请求该服务商。当前 Clarity 请求固定为 7 天,但其 Data Export API 只接受 1–3 天。服务商可能因此拒绝这项报表检查,这不能说明脚本未安装。
记录自己的事件
不写代码也可以测试:在 分析配置 的 上报测试事件 卡片中保留默认值,或选择 分类 并填写 事件名,点击 上报事件。看到 事件已记录。 即表示已保存。
在受信任的服务端代码中也可以这样记录产品事件。该函数本身不做权限检查,不要直接暴露给浏览器:
import { trackAnalyticsEvent } from "@/server/services/analytics-support.service";
await trackAnalyticsEvent({
type: "product",
name: "project_created",
userId: user.id,
path: "/app/projects",
locale: "zh",
value: 1,
});type 取值为 product、revenue、ai、api、acquisition、support 或 retention。事件只保存在你的数据库中,不会发送给外部服务商。
如需按国家查看账号与已结算订单,见独立的国家与地区指南。该页面读取本地账号与订单记录,不使用服务商报表。
验证
- 关闭广告拦截扩展,用无痕窗口打开一个公开页面,例如
/或/pricing。 - 查看网页源代码,找到对应脚本:Google Analytics 或 Google Ads 是
googletagmanager.com/gtag/js,Umami 是带有你的data-website-id的 script,Plausible 是带有你的data-domain的 script,Clarity 是clarity.ms/tag,Crisp 是client.crisp.chat/l.js。 - 在服务商的实时视图中确认这次访问已被记录。Crisp 会在页面角落显示聊天气泡。
- 保存了 Google Analytics、Umami、Plausible 或 Clarity 任一标识后,
/setup中 分析供应商 显示为就绪。
在仓库中,pnpm validate:analytics 会检查配置、事件、报表拉取与权限。
常见问题
保存时报格式错误
Google Analytics ID 必须形如 G-XXXXXXXX,Property ID 必须是纯数字,Google Ads ID 必须形如 AW-XXXXXXXX。三者都合法之前不会保存任何内容。
服务商报表显示失败
服务商拒绝了请求,报告中带有 HTTP 状态和响应内容的开头部分。对于 Google Analytics,确认 access token 未过期且有权读取该媒体资源。
页面上没有出现脚本
标识为空、保存后没有刷新页面,或被广告拦截扩展移除。先看 运行检查 面板,再关闭扩展后刷新。
Crisp 组件显示 "Invalid website"
保存的 Crisp Website ID 与 Crisp 账号中的网站不一致。从 Crisp 复制正确的 ID 后重新保存。