How do I improve accuracy of “Time spent on page” and “Visit duration” metrics?

On-Premise

The Average Time on Page metric in Matomo’s Page reports helps you understand how long visitors spend on individual pages. From Matomo 6.0.0 (RC), improvements to the underlying calculation provide more accurate results by default, without requiring additional tracking configuration.

For greater accuracy, particularly when visitors leave without another tracked interaction, you can enable the Heartbeat Timer. Developers can also supply browser-measured time using pv_time for more advanced tracking requirements.

This guide explains how Matomo calculates Time on Page and the options available if you want to improve measurement accuracy even further.

Choose a measurement option

Choose an option based on the level of accuracy you need and the tracking changes you can make. The default calculation requires no additional setup. The Heartbeat Timer and pv_time integration are optional configurations.

1. Default Time on Page calculation

Matomo records time separately for each pageview, improving how subsequent events and other tracked interactions are attributed to that page.

view avg time on page in report

The default calculation provides:

  • More accurate attribution of time to individual pages, including when visitors trigger events or other tracked interactions.
  • Better attribution of interactions across tabs when tracking requests include a pageview identifier. Recorded time can still include background or idle time.
  • More reliable Average Time on Page values, particularly when visitors read a page before triggering another tracked action.

No additional tracking configuration is required.

Note: The default calculation still needs another tracking request to measure elapsed time. Time on the last page of a visit, or time spent reading before leaving without another tracked interaction, may remain unrecorded or underestimated.

You can optionally enable the Heartbeat Timer for better measurement in these situations. Developers can also supply browser-measured time using pv_time, but this does not guarantee focus-only measurement.

2. Enable the Heartbeat Timer for higher accuracy (optional)

The Heartbeat Timer sends additional timing information to Matomo when visitors leave or hide a page, subject to its configured minimum interval. It measures time when no further interaction is tracked. Heartbeat pings do not count as hits.

With the improved Time on Page calculation, the Heartbeat Timer helps Matomo better measure:

  • Time spent reading without clicking or performing other tracked interactions.
  • Time spent on the last page of a visit.
  • Time associated with switching tabs or leaving a page.
  • Visits where several pages are open in different tabs.

To enable it, add this line to your Matomo JavaScript tracking code:

_paq.push(['enableHeartBeatTimer']);

See the Heartbeat Timer developer guide for setup details and timing options.

Note: Although the Heartbeat Timer improves timing across common browsing scenarios, complex multi-tab behaviour may still be difficult to measure accurately.

For more advanced requirements, such as distinguishing active viewing time from background activity, consider a custom pv_time integration (explained below).

3. Measure page time in the browser with pv_time (optional)

For more advanced requirements, you can calculate time spent on a page directly in the browser and send that value to Matomo using the pv_time tracking parameter.

This provides greater control over how page time is measured. For example, a custom integration can distinguish between time spent actively viewing a page and time when it is open in a background tab.

A client-side integration can support:

  • Measuring time when a page is in focus.
  • Tracking more complex browsing behaviour involving multiple tabs.
  • Accounting for browser-specific behaviour when visitors leave a page.
  • Defining custom criteria for measuring engagement time.

A developer can extend Matomo’s existing JavaScript tracker (matomo.js) to calculate page time in the browser and send it with tracking requests using pv_time.

Accuracy considerations: The recorded time depends on your custom implementation and subsequent tracking activity. Later tracking requests may increase the recorded time to include background or idle time, even when your integration calculates focus time correctly. Browser restrictions or undelivered tracking requests can also affect accuracy.

How the improved time on page affects historical reports

The improved default calculation applies only to data collected after upgrading to Matomo 6.

Historical data retains the previous calculation, even if older reports are regenerated. Reprocessing historical data cannot reconstruct the pageview timing information needed for the calculation.

Reports covering periods before and after the change may therefore contain values calculated using different methods. Keep this in mind when comparing Average Time on Page across the upgrade.

Previous FAQ: How do I control the categories tree structure in the Page URLs and Page titles reports?