企业官网建设流程全解析

Umami 自定义事件埋点指南：3步追踪注册与购买行为

【免费下载链接】umamiUmami is a privacy-first analytics platform. Traffic, campaigns, behavior, conversions, and revenue in one place — no cookies, no surveillance, self-hosted or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/um/umami

运营总问昨天注册了多少人，你只能翻后台肉眼数。Umami 的自定义事件功能，让你用一行脚本记录注册、加购、购买等关键动作，本文覆盖接入、配置到自查的完整路径。

功能定位：从"有人来过"到"做了什么"

Umami 默认只统计页面访问，看不出用户点了哪个按钮、下了几单。自定义事件就是给任意业务动作打点：点击、提交、下单，都能单独记录并带上自己的属性。它适合自托管、不想依赖第三方统计的团队。

原理一句话带过：前端脚本把动作打包成 JSON 提交给 src/pages/api/send.ts 对应的收集接口，接口校验字段后落库，会话用一张签名令牌在浏览器和后端之间保持。

准备工作

• 一个能访问的 Umami 实例。官方支持 MySQL 8.0 以上或 PostgreSQL 12.14 以上，用docker compose up -d即可拉起，细节见 README.md
• 已创建网站，并记下它的 website-id（一串 UUID，在网站设置页可见）
• 能修改被监测页面的源码，才有地方放脚本
• 一个管理员账号，用于登录后核对数据

实施步骤

埋入追踪脚本

把下面这行放进页面 head，替换成你的域名和网站 ID：

<script defer src="https://你的域名/script.js"><button>// 用户成功下单时调用 umami.track('purchase', { value: 199, plan: 'pro' }); umami.identify({ vip: true }); // 把用户属性挂到当前会话上

identify走的是同一个接口，数据存进会话扩展字段，后面看报表时就能按人群拆分。

进阶玩法

场景一：拼一条转化漏斗。给"浏览商品 → 加购 → 支付成功"三个动作各打一个事件，然后在后台的报告区新建漏斗报表。哪个环节掉人最多，一眼可见，比盯着总数猜高效得多。

场景二：区分新老用户。用户登录后立刻调用umami.identify({ type: 'new' })，把身份挂到会话上。之后看事件数据时，新客和老客的下单率可以直接对比，回答"拉新到底有没有用"。

验证与自查

📋 按顺序过一遍，全勾上才算打通：

• 打开被测页面 1 分钟内，后台访问量增加
• 点击带data-umami-event的按钮，事件列表里出现对应名字
• 事件详情里能看到value、plan等自定义属性
• 连续操作 30 分钟内只算一次访问，超过 30 分钟无动作才计新访问
• 爬虫和机器流量没混进数据（接口会先做 UA 判断）
• 自己测试的点击没污染报表（见下方避坑第 3 条）

避坑指南

现象：点了按钮，后台就是没有事件。原因：脚本没加载成功，或data-website-id和当前网站对不上。 处理：打开浏览器开发者工具，确认 script.js 返回 200，再核对 ID 是否与你要上报的网站一致。

现象：同一用户被算成多次访问。原因：会话 30 分钟无动作后，接口会换一个新访问 ID，这是 send.ts 里写死的过期逻辑。 处理：属正常设计，用于区分长短停留；若刷新页面也断，先检查服务器时间是否准确。

现象：自己反复测试，数据全乱了。原因：测试点击和真实用户无法区分。 处理：设置环境变量IGNORE_IP填入你的测试 IP，接口会直接拒绝这些请求，报表立刻干净。

现象：事件名在报表里被截断。原因：事件名和 URL 都有长度上限，超出部分被裁掉。 处理：事件名起短一点，把细节放到属性对象里传。

先给注册和支付按钮埋上事件，一天后就能看清转化断点。下一步建议：打开后台报告区，用漏斗把浏览、加购、购买串起来。

【免费下载链接】umamiUmami is a privacy-first analytics platform. Traffic, campaigns, behavior, conversions, and revenue in one place — no cookies, no surveillance, self-hosted or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/um/umami