页面停留时长统计：从可见时长到心跳上报的完整埋点实践

简介：面向移动端开发、产品运营及数据分析人员，这份资源围绕“用户停留浏览页面的时间统计”场景，提供一套完整且可直接落地的原生iOS实现方案，覆盖事件监听、时间戳记录、间隔奖励与超时累积等关键逻辑，可帮助开发者快速理解、复用并扩展页面停留时长统计功能。压缩包共6个文件，其中包含Objective-C实现代码、对应头文件，以及PNG界面图片，整体体积仅48KB，非常轻量易用。资源已有403人学习，适合需要掌握用户行为数据采集、进行页面活跃度分析或设计留存激励策略的iOS开发者参考。通过学习示例代码，可掌握页面加载、滚动、离开等事件的计时处理，以及定时器、数据上报等配套思路，为优化用户体验和评估广告效果提供数据支撑。 做前端埋点的人应该都有体会，页面停留时长是产品运营最爱看、也是技术最容易埋错的指标之一。运营同学拿着一份导出的停留时长报表，随口来一句“怎么用户只待了10秒就走了”，而你心里清楚，那个10秒很可能只是用户切到别的Tab看了会儿微信，页面一直开着没动过。这篇文章我就从统计口径、实现方案、上报策略到各种边角case，把“用户停留浏览页面的时间统计”这件事完整拆一遍，包含完整可用的代码和我在真实项目里踩过的坑，适合做数据埋点、用户行为分析、增长分析的同学参考。

先亮个观点：不要一上来就写代码，先把统计口径定清楚。同一批用户，按“页面打开总时长”算和按“页面真正可见时长”算，结果能差出30%以上。业务要什么口径，决定了后面所有代码怎么写，这一步想不明白，后面做得再精细都可能白搭。

1. 先定义清楚：你要统计的到底是哪个时间

1.1 三种统计口径与适用场景

先说一个最容易忽略的事实：用户在浏览器里打开一个页面，这个页面处于“存在”的完整时间段，和用户“正在看”的时间段，很少完全重合。最常见的场景就是浏览器开了十几个Tab，用户来回切换，某个页面其实一直开着，但用户可能一分钟都没看过它。

• 页面驻留时长：从用户打开页面到关闭页面、跳转离开或关闭浏览器，按时间戳差值计算的完整时长。这个口径实现最简单，但它把切后台、切Tab、锁屏这些“页面还开着但你没在看”的时间全部算进去了。如果你只是想给运营看一个大致的行为数据，这个口径勉强能用。
• 页面可见时长：只在页面处于可见状态时累加时间。一旦用户切到别的Tab、最小化窗口或锁屏，计时暂停，等用户切回来继续累加。这个口径能比较真实地反映“用户停留在页面内容上的时间”，也是目前业界做内容产品、广告平台时普遍采用的口径。
• 深度互动时长：在可见时长基础上，进一步要求页面产生了用户交互才算时间，比如滚动、点击、键盘输入。连续N秒没有任何交互，这段时间会被剔除。这是精细化运营最想要的口径，但实现复杂度和误判概率都会上升。

三种口径和业务场景的匹配关系，我用表格总结一下：

1.2 口径选错的典型后果

我见过一个内容平台的案例，最初用的是页面驻留时长，结果技术团队优化后接入可见时长，平均停留时长直接掉了40%多。产品经理差点以为是新版本做坏了，后来一查原因，是用户大量多开Tab、后台挂机的时长被旧口径虚提了。

如果你做的是资讯或短视频类产品，用户经常打开页面后扔一边去干别的事，你用驻留时长去评估内容质量，得到的就是严重失真数据。反过来，如果你做的是后台管理系统，用户开着页面去开会、去回复消息是常态，你用可见时长去考核功能使用情况，也会得出不公正的结论。

所以我建议第一步永远是把口径和业务目标对齐，再往下写代码。

2. 从零实现一套可用的统计逻辑

2.1 基础版：进入时间剪离开时间

先看最朴素的实现，用一个全局时间戳，在页面加载时记录，在卸载或关闭时相减。

// 基础版：页面驻留时长 const startTime = Date.now(); window.addEventListener('beforeunload', () => { const duration = Math.round((Date.now() - startTime) / 1000); report({ page: location.pathname, duration }); }); function report(data) { const payload = JSON.stringify(data); if (navigator.sendBeacon) { navigator.sendBeacon('/api/stay', payload); } else { fetch('/api/stay', { method: 'POST', body: payload, keepalive: true, headers: { 'Content-Type': 'application/json' } }); } }

这里面有两个明显问题。第一个，beforeunload只在页面卸载时触发，但移动端浏览器切后台后，页面进程可能被系统直接回收，beforeunload根本不会执行，数据就丢了。第二个，也是最关键的，驻留时长口径没有过滤掉用户不在页面的时间。

基础版的另一个问题是，现代浏览器对Tab切到后台后的JS执行做了严格的定时器节流，如果你在页面里还挂了requestAnimationFrame或高频setInterval做其他统计，后台时会完全停摆，导致所有依赖定时器的逻辑全部失真。

2.2 进阶版：用Visibility API过滤掉隐藏时间

Page Visibility API是解决“用户是否真的在看这个页面”的最基础工具。核心就是document.visibilityState和visibilitychange事件。实现思路很简单：页面可见时计时开始，页面隐藏时把这段可见时间累加，等页面再次可见时重新开始计时。

// 进阶版：页面可见时长 let visibleStartTime = Date.now(); let totalVisibleTime = 0; document.addEventListener('visibilitychange', () => { if (document.visibilityState === 'visible') { // 切回可见，开始计时 visibleStartTime = Date.now(); } else { // 页面被隐藏，把这一段可见时间累加 totalVisibleTime += Date.now() - visibleStartTime; } }); // 兜底：页面直接关闭或跳转时，把最后一次可见片段补上 window.addEventListener('beforeunload', () => { if (document.visibilityState === 'visible') { totalVisibleTime += Date.now() - visibleStartTime; } report({ page: location.pathname, visibleDuration: totalVisibleTime }); });

这个方案的效果已经好了很多，能比较准确地统计“用户在页面上真实浏览”的时间。有几个细节值得注意。

visibilitychange事件在页面初次加载时也会触发，需要在初始化时把visibleStartTime设置好，否则会把加载前的一小段时间误算进去。另一个常见坑是，在iOS Safari上，用户下拉关闭页面的交互行为，可能让beforeunload和pagehide的触发顺序和桌面端不一致，导致最后一段可见时间没有被累加。我建议在pagehide事件里也做一次相同的兜底累加，页面即使走的是pagehide而不是beforeunload，也不会漏算最后一小段时间。

2.3 完整版：心跳上报，防丢失也防冻结

进阶版仍然有一个问题：如果用户页面可见但网络不稳定，或者浏览器进程被系统直接回收，关闭时那一次上报依然可能失败。所以生产环境我推荐“心跳上报+关闭兜底”双通道。

// 完整版：心跳上报 + 关闭兜底 const HEARTBEAT_INTERVAL = 5000; let currentDuration = 0; let lastCheckTs = Date.now(); let timer = null; function startTimer() { if (timer) return; timer = setInterval(() => { const now = Date.now(); if (document.visibilityState === 'visible') { currentDuration += (now - lastCheckTs) / 1000; report({ page: location.pathname, visibleDuration: currentDuration, ts: now }); } lastCheckTs = now; }, HEARTBEAT_INTERVAL); } window.addEventListener('load', startTimer); window.addEventListener('pagehide', () => { const now = Date.now(); if (document.visibilityState === 'visible') { currentDuration += (now - lastCheckTs) / 1000; } report({ page: location.pathname, visibleDuration: currentDuration, final: true }); clearInterval(timer); });

心跳机制的核心思路是：每5秒检查一次页面是否可见，可见就用当前时间减去上次检查的时间，把差值累加，并立刻上报一次。这样即使最后关闭页面的上报失败，服务端已经收到了前面的心跳数据，最多丢失最后几秒的精度。

为什么用累加而不用记录开始时间和结束时间？因为心跳上报天然是“增量”的，服务端按session维度取最大值，就能还原整个会话的时长。如果按时间戳上传，服务端还需要额外做一次时间区间合并，在跨设备、跨网络的情况下很容易算出错误值。

3. 上报环节：关闭页面的最后一秒也要保住数据

3.1 为什么不能用普通fetch或XHR做离开上报

页面在关闭或跳转的一瞬间，浏览器会中止当前页面里所有尚未完成的网络请求。普通fetch和XHR请求在这时候发出去，大概率直接被cancel，后端连请求日志都看不到。

很多团队踩过这个坑：统计代码写在beforeunload里，用普通axios发请求，本地调试怎么测都正常，真机上数据就是丢一大片。原因就是浏览器对“页面卸载期间”的请求做了特殊处理，普通异步请求根本来不及送达。

3.2 sendBeacon与fetch keepalive的搭配方案

navigator.sendBeacon是专门为这种场景设计的API，它在页面卸载时依然能够把数据发给服务端，而且不会阻塞页面关闭流程。它的缺点是默认用POST发送、Content-Type固定为text/plain，有些后端直接收JSON的地方需要做一层兼容。

function report(payload) { const data = JSON.stringify(payload); try { if (navigator.sendBeacon) { navigator.sendBeacon('/api/stay', new Blob([data], { type: 'application/json' })); return; } const controller = new AbortController(); setTimeout(() => controller.abort(), 1000); fetch('/api/stay', { method: 'POST', body: data, keepalive: true, signal: controller.signal, headers: { 'Content-Type': 'application/json' } }); } catch (e) { // 静默失败，埋点不要影响业务 } }

这里用Blob包装一下，可以把Content-Type调成application/json，后端解析更省事。fetch加了keepalive是sendBeacon的不错降级方案，keepalive支持请求体，但要注意单次请求体大小有限制，别在关闭上报时塞一大包历史数据。

另外要提醒一下，sendBeacon发送的数据量不宜过大，Chrome等浏览器对单次beacon请求有体积限制，一般几KB以内没问题，但别把整个用户行为明细塞进去。我一般只传累计时长、页面标识、sessionId和时间戳四个字段，剩下的细节由服务端按session去关联。

重要提示：埋点上报代码永远不要放在阻塞主流程的位置，也不要做失败重试，丢了就丢了，补不回来只会让你的页面卡顿，得不偿失。

4. 真实环境里的坑，每一个都是数据不准的来源

4.1 后台标签页定时器被冻结

前面提到过，浏览器为了省电，会大幅降低后台Tab的定时器频率，Chrome对后台页面的最小定时器间隔可能会被提升到1分钟甚至更长。如果你只是记录时间戳，影响不大，因为Date.now()不受定时器调度影响。但如果你的累计逻辑依赖setInterval的“每次回调加固定值”，后台时就会漏加一大段时间。

解决办法是，不要在定时器里“推算”时间，而是每次回调时用Date.now()去和上次记录的时间戳做差值。换句话说，定时器只负责触发检查，时间计算永远以真实时钟为准。

let lastCheck = Date.now(); setInterval(() => { const now = Date.now(); if (document.visibilityState === 'visible') { currentDuration += (now - lastCheck) / 1000; } lastCheck = now; report({ page: location.pathname, visibleDuration: currentDuration }); }, 5000);

这样即使定时器被浏览器冻结了很久，下次回调时仍然能通过时间戳差值把这段时间补上，不会漏。

4.2 SPA路由切换与页面进入/离开的判定

单页应用（SPA）的特殊性在于，页面“卸载”不是真实发生的，只是路由变了，DOM被替换。如果还在用beforeunload判断页面关闭，SPA内所有路由切换都不会触发，停留时长就会算成整个会话从进入到最后关闭的总和，结果是完全失效的。

处理方式有两种。一种是在路由框架里手动埋点，比如Vue Router的afterEach、React的useEffect或路由监听器里记录进入时间，切走时结算。另一种是统一封装一个页面生命周期管理器，把路由变化视为“页面离开”处理，上报完成后再开启一个新的计时段。

// 以 Vue Router 为例 router.afterEach((to, from) => { if (from.name) { const duration = calculateDuration(); report({ page: from.path, visibleDuration: duration }); } resetTimer(); });

这种处理方式也能自然支持页面间的会话串联，不过要注意，SPA里如果用户停留在同一条路由但参数变化了，是否要算新页面，需要和业务对齐。

4.3 多标签页同时打开同一个页面

只要用户开了两个Tab访问同一个页面，两个Tab就会各自计时各自上报，如果服务端只按session或userId去聚合，同一时间段就会被重复记录两次。

处理思路是给每个页面实例生成一个唯一的sessionId，上传时带上。服务端聚合时先按sessionId去重，再按userId汇总，而不是直接sum。这样即使多Tab存在，也能准确区分。

4.4 移动端锁屏、切后台与进程回收

移动端的坑比桌面端更多。iOS在内存紧张时会直接杀掉后台页面，Android厂商的省电策略五花八门，很多情况下beforeunload和pagehide都来不及触发。所以移动端必须要靠心跳上报兜底，把上报频率控制在合理范围（5到10秒比较稳妥），心跳间隔太短会带来额外流量开销，太长会造成数据丢失明显。

5. 从“能用”到“好用”的进阶建议

5.1 上报数据的合理性校验

收到数据后，先别急着喂给报表，要做几次基础校验。比如时长明显超过24小时的数据要能过滤掉，单条Session里多次上报时长递减（正常应该递增）的要能识别，跨设备的时间戳错乱会带来负数差值，也要清洗。

我一般在服务端做三层校验：第一层过滤大于最大阈值的异常值，第二层校验时间戳是否在合理范围内，第三层按sessionId做单调性检查。这些逻辑写起来不难，但能有效保证下游报表的可信度，比用画图工具做各种可视化重要得多。

5.2 从“停留时长”延伸到更宽的分析指标

最后一个建议，把停留时长作为基础事件，围绕它继续扩展。比如加上页面滚动深度，可以分析用户是否真的把内容看完了；加上页面元素曝光，可以判断哪一块内容最吸引人；结合页面切换事件，能还原用户在站内的完整浏览路径。

我曾经在一个内容项目里，把“可见时长”和“滚动深度”联合起来看，发现很多用户的可见时长很长、但滚动深度很低，原因是页面悬浮播放器一直在播放视频，用户开着页面的声音听，压根没往下翻。这种情况下单纯优化停留时长指标，方向就会跑偏。

所以做埋点统计的目标不是把数字做漂亮，而是把它变成可以指导产品和运营决策的依据。每次加一个指标，都要回到那个最初的问题：它到底在度量哪个行为？用户做了什么样的动作才会让这个数字变大或变小？

以上是我在多个项目里把“用户停留浏览页面的时间统计”从简单到完整搭建的真实过程，希望能帮你在做数据埋点时少走点弯路。最后再分享一个小工具建议：开发阶段在控制台里把visibilitychange和上报日志都打印出来，手动切Tab、锁屏、开关浏览器各测一遍，比写好代码就直接上线要靠谱得多。

本文还有配套的精品资源，点击获取