This guide explains what the pageVisibilityTracker plugin is and how to integrate it into your analytics.js tracking implementation.
It's becoming increasingly common for users to visit your site, and then leave it open in a browser tab for hours or days. And with rise in popularity of single page applications (SPAs) and progressive web apps (PWAs) some tabs almost never get closed.
Because of this shift, the traditional model of pageviews and sessions simply does not apply in a growing number of cases.
The pageVisibilityTracker plugin changes this paradigm by shifting from page load being the primary indicator to Page Visibility. To understand why this is important, consider this scenario: you've just updated your website to be able to fetch new content in the background and display it to the user when they return to your page (without forcing them to reload). If you were only using the default analytics.js tracking snippet, this change would result is dramatically fewer pageviews, even though the user is consuming the same amount of content.
By taking Page Visibility into consideration, the pageVisibilityTracker plugin is able to report consistent numbers regardless of whether the user needs to reload the page.
The pageVisibilityTracker plugin also calculates how long a given page was in the visible state for a given session, which is a much better indicator of user engagement than Session Duration.
The following sample reports show how you can use the pageVisibilityTracker plugin to more accurately measure user engagement with your content.
Top pages by visible time:
Traffic origins (source/medium) resulting in the longest visible sessions:
The pageVisibilityTracker plugin listens for visibilitychange events on the current page and sends hits to Google Analytics capturing how long the page was in the visible state. It also programmatically starts new sessions and sends new pageviews when the visibility state changes from hidden to visible (if the previous session has timed out).
Optionally you can set configuration options to let the pageVisibilityTracker plugin handle sending the initial pageview. When set, the plugin will send the initial pageview if the page is loaded in the visible state. If it's loaded in a background tab, the plugin will wait until the page is visible before sending the inital pageview.
Note: if you configure the pageVisibilityTracker plugin to send the initial pageview, make sure you remove the ga('send', 'pageview') command from your tracking snippet.
When using the pageVisibilityTracker plugin, you may notice an increase or decrease in session and pageview counts. This is not an error, the reality is your current implementation (based just on page loads) is likely inaccurate.
If your users tend to leave your site open in a background tab and switch to it frequently, you'll likely notice an increase in session and pageview counts. By contrast, if a significant portion of your users load your site in a background tab and later close the tab without ever viewing the content, you'll likely see your session and pageview counts go down.
Note: you can set the pageLoadsMetricIndex option to track page loads (via a custom metric) separately from pageviews in the event you also want to know how often your pages are loaded.
To enable the pageVisibilityTracker plugin, run the require command, specify the plugin name 'pageVisibilityTracker', and pass in any configuration options (if any) you wish to set:
ga('require', 'pageVisibilityTracker', options);The easiest way to track the time a page was visible is to create a custom metric called Page Visible Time that you set in your plugin configuration options, and then to create calculated metrics called Avg. Page Visible Time (per Page) and Avg. Page Visible Time (per Session) that you use in your reports.
Which calculated metric you need will depend on which dimensions you're using in your report. For session-level dimensions (e.g. Referrer or Device Category) you'll want to use the session version, and for page-specific dimensions (e.g. Page or Title) you'll want to use the page version.
Here are the formulas for both:
{{Page Visible Time}} / {{Sessions}}
{{Page Visible Time}} / {{Unique Pageviews}}
The screenshots in the overview shows some examples of what reports with these custom and calculated metrics look like.
The following table outlines all possible configuration options for the pageVisibilityTracker plugin. If any of the options has a default value, the default is explicitly stated:
| Name | Type | Description |
|---|---|---|
sessionTimeout |
number |
The session timeout amount (in minutes) of the Google Analytics property. By default this value is 30 minutes, which is the same default used for new Google Analytics properties. The value set for this plugin should always be the same as the property setting in Google Analytics. Default: 30
|
timeZone |
string |
A time zone to pass to the Int.DateTimeFormat instance. Since sessions in Google Analytics are limited to a single date in the time zone of the view, this setting can be used to more accurately predict session boundaries. (Note: if your property contains views in several different time zones, do not use this setting).
|
visibleThreshold |
number |
The time in milliseconds to wait before sending a Page Visibility event (or a new pageview in the case of a session timeout). This helps prevent unwanted events from being sent in cases where a user is quickly switching tabs or closing tabs they no longer want open. Default: 5000
|
sendInitialPageview |
boolean |
When true, the plugin will handle sending the initial pageview. If the page is loaded in the visible state, a pageview is sent right away. If the page is loaded in a background tab, the plugin will wait until the page becomes visible before sending the pageview. Important: If you use this option, make sure you remove the |
pageLoadsMetricIndex |
number |
If this option and the sendInitialPageview option are both set, a custom metric at the index provided is set on the first hit to track page loads. If the page is loaded in the visible state, the custom metric is set on the pageview hit. If the page is loaded in a background tab, an event is sent with the custom metric set on it. See the page load hits section for field details.
|
visibleMetricIndex |
number |
If set, a custom metric at the index provided is sent when the page's visibility state changes from visible to hidden. The metric value is the amount of time (in seconds) the page was in the visible state. |
fieldsObj |
Object |
See the common options guide for the fieldsObj description. |
hitFilter |
Function |
See the common options guide for the hitFilter description. |
The pageVisibilityTracker plugin sets the following default field values on event hits it sends. To customize these values, use one of the options described above.
| Field | Value |
|---|---|
hitType |
'event' |
eventCategory |
'Page Visibility' |
eventAction |
'track' |
eventValue |
The elapsed time (in seconds) spent in the visible state. |
nonInteraction |
true |
If the page's visibility state changes from hidden to visible and the session has timed out, a new pageview is sent.
| Field | Value |
|---|---|
hitType |
'pageview' |
If the sendInitialPageview option is set and the page's visibility state is visible, a pageview is sent with the following default field values:
| Field | Value |
|---|---|
hitType |
'pageview' |
If the pageLoadsMetricIndex option is set in addition to the sendInitialPageview option (and the page was loaded in the visible state), a pageview is sent with the following default field values:
| Field | Value |
|---|---|
hitType |
'pageview' |
metric<pageLoadsMetricIndex> |
1 |
If the sendInitialPageview and pageLoadsMetricIndex options are set, and the page was loaded in a background tab, an event is sent with the following default field values:
| Field | Value |
|---|---|
hitType |
'event' |
eventCategory |
'Page Visibility' |
eventAction |
'page load' |
metric<pageLoadsMetricIndex> |
1 |
nonInteraction |
true |
The following table lists all methods for the pageVisibilityTracker plugin:
| Name | Description |
|---|---|
remove |
Removes the pageVisibilityTracker plugin from the specified tracker, removes all event listeners from the DOM, and restores all modified tasks to their original state prior to the plugin being required. |
For details on how analytics.js plugin methods work and how to invoke them, see calling plugin methods in the analytics.js documentation.
To let the pageVisibilityTracker plugin handle sending the initial pageview for you when the page is visible, set the sendInitialPageview option to true:
ga('require', 'pageVisibilityTracker', {
sendInitialPageview: true,
});Note that when using the sendInitialPageview option, you no longer need the ga('send', 'pageview') command in your tracking snippet:
ga('create', 'UA-XXXXX-Y', 'auto');
// Require other autotrack plugins as needed.
ga('require', 'pageVisibilityTracker', {
sendInitialPageview: true,
});
// The command below is no longer needed.
// ga('send', 'pageview');If you've set the default session timeout in your Google Analytics property to 4 hours and the timezone of all your views to Pacific Time, you can ensure the pageVisibilityTracker plugin knows about these settings with the following configuration options:
ga('require', 'pageVisibilityTracker', {
sessionTimeout: 4 * 60,
timeZone: 'America/Los_Angeles',
});If you want to track page load (in addition to pageviews) as well as the total (or average) time a user spends in the visible state on your site, you can do so via custom metrics and the pageLoadsMetricIndex and visibleMetricIndex options.
ga('require', 'pageVisibilityTracker', {
sendInitialPageview: true,
pageLoadsMetricIndex: 1,
visibleMetricIndex: 2,
timeZone: 'America/Los_Angeles',
});Note: this requires creating custom metrics in your Google Analytics property settings.