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 put that another way, if a user visits your application and interacts with it, switches to a different tab, and then comes back to your application hours or days later. Whether they reloaded the page or not, with the pageVisibilityTracker enabled, this will be considered a new pageview and a new session.
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.
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
|
changeTemplate |
Function |
A function that accepts the old and new values and returns a string to be used as the eventLabel field for change events.Default: |
hiddenMetricIndex |
number |
If set, a custom metric at the index provided is sent when the page's visibility state changes from hidden to visible. The metric value is the amount of time (in seconds) the page was in the hidden state. |
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 |
'change' |
eventLabel |
options.changeTemplate() |
eventValue |
The elapsed time since the session start or the previous change event. |
nonInteraction |
true if the visibility state is hidden, false otherwise. |
Note: the reference to options refers to passed configuration options.
If the page's visibility state changes from hidden to visible and the session has timed out. A pageview is sent instead of a change event.
| Field | Value |
|---|---|
hitType |
'pageview' |
While not a feature enabled by default, the pageVisibilityTracker plugin is also capable of dramatically improving the accuracy of session duration calculations.
Session duration in Google Analytics is defined as the amount of time between the first interaction hit and the last interaction hit within a single session. That means that if a session only has one interaction hit, the duration is zero, even if the user was on the page for hours!
The pageVisibilityTracker plugin defaults to sending visibility state change events as non-interaction hits (for the hidden event), but you can customize this to make all hits interactive and since most sessions will contain visibility state change events, your sessions durations will become much more accurate.
The downside of this approach is it will alter your bounce rate. However, for many users, this trade-off is worth it since bounce rate can be calculated in other ways (e.g. with a custom segment).
The examples section below includes a code sample showing how to make all events interaction events.
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.
This example uses the fieldsObj option to set the nonInteraction value for all hits to null, which overrides the plugin's default nonInteraction value of true for hidden events. Making this change will dramatically improve session duration calculations as described above.
ga('require', 'pageVisibilityTracker', {
fieldsObj: {
nonInteraction: null
}
});Setting custom metrics to track time spent in the hidden and visible states
If you want to track the total (or average) time a user spends in each visibility state via a custom metric (by default it's tracked as the eventValue), you can use the hidden and visible metric indexes.
ga('require', 'pageVisibilityTracker', {
hiddenMetricIndex: 1,
visibleMetricIndex: 2,
});Note: this requires creating custom metrics in your Google Analytics property settings.