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, 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 pageload 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 pageVisibilityTracker plugin listens for visibilitychange events on the current page and sends hits to Google Analytics capturing how long the page was in each 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).
When using the pageVisibilityTracker plugin, you'll probably notice an increase in your session and pageview counts. This is not an error, the reality is your current implementation (based just on pageloads) is likely underreporting these metrics.
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 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).
|
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 |
'visible' |
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' |
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.
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 maxScrollTracker plugin knows about these settings with the following configuration options:
ga('require', 'maxScrollTracker', {
sessionTimeout: 4 * 60,
timeZone: 'America/Los_Angeles',
});If you want to track the total (or average) time a user spends in the visible state via a custom metric (by default it's tracked as the eventValue), you can use the visible metric indexes.
ga('require', 'pageVisibilityTracker', {
visibleMetricIndex: 1,
});Note: this requires creating custom metrics in your Google Analytics property settings.