time on page

docs/metrics-definitions.md

@@ -22,10 +22,13 @@ If you have issues with high bounce rates on your site, you can try to set up so
 
 Shows the browsers used by your visitors. We only show the brand of the browser and when you click on the brand you can see the version number too. Metrics are shown as a percentage of all visitors and the total number of unique visitors.
 
-## Conversion Rate
+## Channels
 
-The percentage of visitors that take a desired action such as subscribing to a newsletter or signing up for an account. Calculated as follows:
-unique conversions for a goal / unique visitors, where both values depend on the filters applied to the dashboard.
+Channels show a breakdown of your traffic sources categorized into high-level groups such as "Organic Social", "Paid Search" and "Email". Learn more [here](top-referrers.md).
+
+## Conversion Rate (or CR)
+
+The percentage of visitors that take a desired action such as subscribing to a newsletter or signing up for an account. Calculated as follows: unique conversions for a goal / unique visitors, where both values depend on the filters applied to the dashboard.
 
 ## Custom Properties (or Custom Dimensions)
 
@@ -57,9 +60,9 @@ Automatically track the number of file downloads. This feature isn't enabled by
 
 ## Funnels
 
-You can follow the visitor journey from a landing page to a conversion with [funnel analysis](funnel-analysis.md). 
+You can follow the visitor journey from a landing page to a conversion with [funnel analysis](funnel-analysis.md).
 
-## Goals
+## Goals (or Events)
 
 You can use goals to track desired actions people take on your site. Goals can be based on people [visiting a particular page](pageview-goals.md) or [triggering a particular event](custom-event-goals.md) such as subscribing to a newsletter or signing up for an account. You can even use custom properties to create your own metrics to collect and analyze data that Plausible doesn’t automatically track.
 
@@ -89,17 +92,25 @@ Shows the devices used by your visitors. Devices are categorized into desktop, m
 
 ## Scroll Depth
 
-Measures how far visitors scroll down a webpage. It represents the percentage of a page’s total height that visitors have reached on average. You can learn how we calculate it [here](http://plausible.io/docs/scroll-depth).```
+Measures how far visitors scroll down a webpage. It represents the percentage of a page’s total height that visitors have reached on average. You can learn how we calculate it [here](http://plausible.io/docs/scroll-depth).
 
 ## Source
 
 See all referral sources that are sending you traffic. A source is reported when a person clicks through to your site from another site.
 
 ## Time on Page
 
-The average time people spend on a particular page on your site. This is calculated as the difference between the point when a person lands on a particular page and when they move on to the next page.
+The average amount of time spent per visitor viewing a particular page on your site.
+
+Similar to scroll depth, this metric relies on `engagement` events being sent by our tracking script for every pageview when the user navigates to a new page or switches tabs. This allows us to provide you with a more precise and reliable measure of user engagement which includes visitors who bounce away from your pages and which does not include time not spent actively on your pages.
+
+<details>
+<summary>Legacy time on page metric</summary>
+
+Prior to a tracker script upgrade in March 2025, we used a different method to calculate time on page, instead relying on timestamp of each `pageview` event. This method was both prone to over-estimating time spent on a page and was unable to provide measurements on pages where visitors bounced.
 
-You may notice differences in the time on page in Plausible and in Google's Universal Analytics. This is because we have a different definition. In Google Analytics (UA), bounced visitors are included in the time on page calculation but are set to 10 seconds. In Plausible, we exclude bounced visitors from the time on page calculation. Neither of these approaches is 100% accurate. Plausible would show higher than the actual time on page, and Google Analytics would show lower than the actual time on page. In both cases, it's not possible to measure the time on page of people that bounce from your site. 
+For dates prior to the new tracker upgrade, the legacy time on page metric is displayed along with a note in the tooltip.
+</details>
 
 ## Total Conversions
 

docs/stats-api.md

@@ -94,7 +94,7 @@ Valid metrics are:
 | `group_conversion_rate` | `float` | The percentage of visitors who completed the goal with the same dimension. Requires: dimension list passed, an event:goal filter or event:goal dimension | Requires non-empty `dimensions`, event:goal filter or dimension being set |
 | `average_revenue` | `Revenue` or null | Average revenue per revenue goal conversion | Requires [revenue goals](docs/ecommerce-revenue-tracking.md), `event:goal` filter or dimension for a relevant revenue goal. |
 | `total_revenue` | `Revenue` or null | Total revenue from revenue goal conversions | Requires [revenue goals](docs/ecommerce-revenue-tracking.md), `event:goal` filter or dimension for a relevant revenue goal. |
-
+| `time_on_page` | `int` | Average time in seconds spent on a page per visit | Requires `event:page` filter or dimension being set. |
 
 <details>
   <summary>Read more about revenue metrics</summary>