自建访问统计:SSR 采集、心跳和会话合并
用前端埋点统计 PV,常见结果是首屏漏记、刷新重复、切后台后停留时长还在涨。原因通常不是埋点少,而是把“页面渲染”“路由切换”“页面可见性”混成了同一个事件。本文按门户的自建统计实现,说明服务端和浏览器各自负责什么、会话怎么合并,以及看板聚合时最容易写错的 SQL 顺序。
先给结论
访问统计要分两层:
- 服务端在每次 HTML 渲染时记首屏 PV,能拿到真实 IP、UA、Referer,也不依赖 JavaScript 是否执行。
- 浏览器只补服务端看不到的部分:SPA 路由切换、页面可见性变化、停留时长和会话续期。
两层用同一套 visitorId、sessionId 和路径口径,事件才能在后台合并。首屏 PV 只由服务端记一次,客户端不要重复记;否则刷新一次就多一次 PV。
现象:PV 重复、时长不动、会话碎掉
| 现象 | 常见原因 |
|---|---|
| 首屏 PV 是 2 | 服务端记了一次,客户端挂载后又记一次 |
| 刷新一次 PV 加 2 或 3 | SPA 路由钩子和页面加载都上报 PV |
| 后台标签页停留时长一直涨 | 没有在 visibilitychange 时停止计时 |
| 同一用户被算成多个会话 | 会话 cookie 没有滑动续期,或客户端每次新生成 |
| 页面排行平均停留恒为 0 | 聚合时先过滤了 pv,再对 leave 的时长求平均 |
| 错误页进入排行 | 没排除 __nuxt_error 或静态资源 |
这些问题单独看都像“埋点不准”,实际是事件边界没有定义清楚。
服务端:只统计 HTML 页面渲染
门户在 Nitro 中间件里采集,判断条件有五条:
function isPageRender(event: any): boolean {
if (event.method !== 'GET') return false
const path: string = event.path || ''
if (!path.startsWith('/')) return false
if (
path.startsWith('/_nuxt') ||
path.startsWith('/_ipx') ||
path.startsWith('/imgly-data') ||
path.startsWith('/__nuxt_error')
) {
return false
}
const lastSegment = path.split('/').pop() || ''
if (lastSegment.includes('.')) return false
const accept = String(event.node.req.headers.accept || '')
return accept.includes('text/html')
}
逐条对应一个误判来源:
| 条件 | 排除的情况 |
|---|---|
GET | 表单提交、API 写请求 |
路径以 / 开头 | 非法或内部路径 |
排除 /_nuxt、/_ipx | JS、CSS、图片优化资源 |
排除 /imgly-data | 图片编辑器的本地数据路由 |
排除 /__nuxt_error | 错误页的内部二次渲染 |
最后一段不含 . | .png、.ico、.js 等静态文件 |
Accept 含 text/html | fetch 的 JSON、图片、流式请求 |
/__nuxt_error 这一条尤其重要。Nuxt 渲染错误页时会内部再走一次中间件,真实路径在外层已经记过;不排除,错误页会把排行和 PV 都污染一遍。
会话和访客 cookie
服务端在响应里种两个 cookie:
| Cookie | 有效期 | 用途 |
|---|---|---|
vid | 1 年 | 访客标识,用于 UV |
sid | 30 分钟 | 会话标识,用于会话数和停留 |
sid 是滑动过期:每次页面渲染或事件上报都会重新写一次 30 分钟。用户持续访问时,会话不会因为固定 30 分钟到期而断成两段;停止访问 30 分钟后,下一次访问才生成新会话。
setCookie(event, VISITOR_COOKIE, visitorId, {
maxAge: 60 * 60 * 24 * 365,
path: '/',
sameSite: 'lax'
})
setCookie(event, SESSION_COOKIE, sessionId, {
maxAge: 60 * 30,
path: '/',
sameSite: 'lax'
})
cookie 值损坏或伪造时,decodeURIComponent 可能抛错。两端的读取函数都按“缺失”处理,再用新 UUID 覆盖,避免统计上报把页面渲染打断。
路径口径:剥掉语言前缀
同一个页面有 /zh/about、/en/about 和无前缀的 /about。如果直接按 event.path 排行,一个页面会被拆成三份。服务端和客户端都剥掉已知语言前缀:
for (const prefix of ['/zh-Hant', '/zh', '/en']) {
if (statsPath === prefix) {
statsPath = '/'
break
}
if (statsPath.startsWith(prefix + '/')) {
statsPath = statsPath.slice(prefix.length)
break
}
}
前缀顺序必须长的在前,/zh-Hant 放在 /zh 前面,否则会被短前缀先匹配,剩下 -Hant/...。
客户端:只补服务端看不到的事件
首屏 PV 已由服务端记录,客户端插件启动时只登记当前位置和进入时间,不再发 PV:
let lastPath = statsPath(router.currentRoute.value.fullPath)
let enteredAt = Date.now()
let left = false
路由切换:leave 和 pv 合并成一个请求
router.afterEach((to) => {
const path = statsPath(to.fullPath)
if (path === lastPath) return
const events: Record<string, unknown>[] = []
if (!left) {
events.push(makeEvent('leave', lastPath, Date.now() - enteredAt))
}
events.push(makeEvent('pv', path))
send({ platform: 'web', events })
lastPath = path
left = false
enteredAt = Date.now()
})
一次导航只发一个请求,events 数组里同时有上一页的 leave 和下一页的 pv。如果分两个请求,网络抖动时可能只到了 PV、没到 leave,停留时长就丢了。
心跳:只在页面可见时续会话
setInterval(() => {
if (document.visibilityState === 'visible') {
event('heartbeat', lastPath)
}
}, 30_000)
心跳有三个作用:
- 续期
sid,让持续阅读不被 30 分钟边界切断。 - 让服务端知道这个会话仍然活跃。
- 给停留时长一个上限参考,避免用户直接关掉进程时完全没记录。
页面隐藏时不发心跳。后台标签页停留不计入本页时长,这是有意为之:用户没有在看页面,不应该算阅读时间。
离开:visibilitychange 和 pagehide 去重
const leaveOnce = (): void => {
if (left) return
left = true
event('leave', lastPath, Date.now() - enteredAt)
}
document.addEventListener('visibilitychange', () => {
if (document.visibilityState === 'hidden') {
leaveOnce()
} else {
left = false
enteredAt = Date.now()
}
})
window.addEventListener('pagehide', leaveOnce)
visibilitychange 和 pagehide 经常在同一时刻触发,left 标志保证只发一次 leave。切回前台时 left 复位,enteredAt 重新起算,后台时间不会被算进停留。
用 fetch(..., { keepalive: true }) 而不是 navigator.sendBeacon,是因为上报体很小,keepalive 足够,而且能统一走 JSON 和现有 API 封装。它不保证一定送达,统计失败会静默丢弃,不影响页面。
事件合并:PV、UV、会话和停留
四个指标的口径要分开:
| 指标 | 口径 | 不能怎么做 |
|---|---|---|
| PV | pv 事件条数 | 把 heartbeat 也算进去 |
| UV | 去重后的 visitorId | 按 IP 去重,NAT 下会严重偏低 |
| 会话数 | 去重后的 sessionId | 按天固定切分会话 |
| 平均停留 | leave 事件的 durationMs 平均 | 先过滤 pv 再对所有事件求平均 |
| 跳出率 | 只有 1 个 PV 的会话占比 | 用 PV 总数除以会话数 |
最隐蔽的错误是停留时长的聚合顺序。durationMs 只出现在 leave 事件里,如果 SQL 写成:
SELECT path, AVG(duration_ms)
FROM stats_event
WHERE event_type = 'pv'
GROUP BY path;
那么参与平均的行全是 pv,duration_ms 为 NULL 或 0,页面排行的平均停留会恒为 0。正确做法是先按会话和页面聚合 leave,或者只对 event_type = 'leave' 求平均,再和 PV 排行关联。
SELECT path, AVG(duration_ms) AS avg_dwell
FROM stats_event
WHERE event_type = 'leave' AND duration_ms > 0
GROUP BY path;
看板的五个接口——概览、页面排行、渠道、设备、地域——应该共享同一套时间范围和过滤条件,否则同一段时间的 PV 在不同卡片上会对不上。
验证:一次访问应该产生哪些事件
| 操作 | 期望事件 |
|---|---|
| 首次打开页面 | 服务端 1 条 pv,客户端不发首屏 PV |
| 点击站内链接 | 1 个请求,含上一页 leave + 新页 pv |
| 停留 30 秒 | 1 条 heartbeat |
| 切到后台 5 分钟 | 1 条 leave,duration 约为前台停留时间 |
| 切回前台 | 不发事件,重新计时 |
| 关闭标签页 | 若之前没发过 leave,补 1 条;已发过则不重复 |
验证时看 Network 面板的请求体和 cookie,不要只看页面上的数字。数字是聚合结果,错了很难反推是采集、合并还是查询的问题。
边界与坑
预取可能被算成 PV。 只按 GET + text/html + 无扩展名 过滤,浏览器或框架预取的 HTML 也可能符合条件。需要更严格时,再检查 Purpose、Sec-Purpose 等请求头。
爬虫和监控会进入统计。 服务端采集不区分人机。对 PV 绝对值要求高时,要加 UA 过滤或独立的机器人规则。
keepalive 不是可靠投递。 它只保证请求在页面卸载时尽量发出,不保证到达。统计允许丢失,不要把它当计费数据。
会话 cookie 过期后,隐藏的标签页不会自动续期。 后台不发心跳,超过 30 分钟再回来会产生新会话。这是会话语义的自然结果,不是丢数据。
IP 不是用户。 同一个 NAT 后面可能有几百个访客;用 IP 算 UV 会严重偏低。IP 只适合做地域和风控参考。
看板查询要统一口径。 PV、UV、会话、停留来自不同事件类型,过滤条件必须一致。先过滤事件类型再聚合,是最容易写反的一步。
相关工具
排查上报里的 User-Agent 时,可以用 UA 解析工具 对照浏览器和爬虫标识;需要看请求链路时用 Traceparent 生成工具。更多自建服务和前端埋点的记录放在 技术笔记。
FAQ
为什么首屏 PV 要放在服务端记?
服务端在 HTML 渲染时就能拿到请求,不依赖 JavaScript 是否执行,也能直接读到 IP、UA 和 Referer。客户端再记一次会重复,刷新时尤其明显。
会话为什么要 30 分钟滑动续期?
固定过期会把持续阅读切成多段;滑动过期让活跃会话保持连续,停止访问 30 分钟后才结束。心跳和每次事件上报都会续期。
后台标签页为什么不算停留时长?
用户没有在看页面,算进去会虚高。页面隐藏时上报 leave,切回前台重新计时,停留只统计可见时间。
为什么页面排行的平均停留会是 0?
常见原因是 SQL 先过滤 event_type = 'pv',再对 duration_ms 求平均,而时长只存在于 leave 事件。应按 leave 聚合停留,再和 PV 关联。
自建统计不难在采集,难在事件边界:首屏只记一次、路由合并上报、隐藏即离开、聚合前分清事件类型。把这四条固定下来,PV 和停留才有解释力。
评论
还没有评论,来说两句吧