添加统计分析与客服聊天

在所有页面加载 Google Analytics、Umami、Plausible、Clarity 或 Crisp 聊天组件,检查连接,并按国家查看统计。

在管理后台保存服务商的标识后,它的脚本会在所有页面加载。再保存 API 凭据,就能拉取报表确认连接。所有服务商都是可选的,彼此独立,都不读取环境变量。

准备工作

  • 在要使用的服务商为自己的域名创建好站点或项目。
  • 具备 config.write 的管理员账号。只有 config.read 可以打开页面,但不能保存、拉取报表或上报测试事件。
  • 按国家查看统计需要 countries.read。

每个服务商分两部分:公开标识用于加载脚本,API 凭据只在管理员拉取报表时使用。

服务商用途加载脚本所需拉取报表所需
Google Analytics在 GA4 中查看访问和事件Google Analytics IDGA Property ID 和 GA Data API Access Token
Google Ads为 Ads 账号加载 Google 代码Google Ads ID不拉取
Umami注重隐私的访问统计,云服务或自托管Umami Website IDUmami API Key
Plausible注重隐私的访问统计,云服务或自托管Plausible DomainPlausible API Key
Microsoft Clarity热力图和会话录屏Clarity Project IDClarity API Token
Crisp在线客服聊天组件Crisp Website ID不拉取

在分析服务商创建站点

厂商适用场景
Google AnalyticsGA4 网页访问与报表
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 天。服务商可能因此拒绝这项报表检查,这不能说明脚本未安装。

记录自己的事件

不写代码也可以测试:在 分析配置 的 上报测试事件 卡片中保留默认值,或选择 分类 并填写 事件名,点击 上报事件。看到 事件已记录。 即表示已保存。

在受信任的服务端代码中也可以这样记录产品事件。该函数本身不做权限检查,不要直接暴露给浏览器:

src/server/services/example.service.ts
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。事件只保存在你的数据库中,不会发送给外部服务商。

如需按国家查看账号与已结算订单,见独立的国家与地区指南。该页面读取本地账号与订单记录,不使用服务商报表。

验证

  1. 关闭广告拦截扩展,用无痕窗口打开一个公开页面,例如 / 或 /pricing。
  2. 查看网页源代码,找到对应脚本: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。
  3. 在服务商的实时视图中确认这次访问已被记录。Crisp 会在页面角落显示聊天气泡。
  4. 保存了 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 后重新保存。

参考

下一步