max-scroll-tracker.md

maxScrollTracker

This guide explains what the maxScrollTracker plugin is and how to integrate it into your analytics.js tracking implementation.

Overview

For each page on your site, the maxScrollTracker plugin tracks how far down the page a user has scrolled, as a percentage of the total scrollable height of the page. For example, if a user scrolls all the way to the bottom of the page, the max scroll percentage tracked is 100%. If they only scroll a third of the way down, 33% is tracked, etc.

The max scroll percentage amounts are calculated on a per-session basis, which means that once a user has scrolled to 100% for a particular page, tracking for that page stops and will only resume when a new session starts.

The following example reports show how you can use the maxScrollTracker plugin to more accurately measure user engagement with your content:

Top pages by scroll depth:

Traffic origins (source/medium) resulting in the highest scroll engagement:

How it works

The maxScrollTracker plugin listens for scroll events on the current page. Once the user starts to scroll, the plugin waits until the user stops scrolling for at least one second (to ensure it doesn't affect scroll performance) and then calculates the percentage the user has scrolled. This value is then compared to the previously calculated value (if one exists), and if there's an increase, an event is sent to Google Analytics with the event value set to the increased amount (and optionally a custom metric) and the event label set to the current scroll percentage.

Tracking the scroll depth as a metric allows you can do calculations and report on things like Avg. Max Scroll Percentage along with any dimension (e.g. Campaign Source, Referrer, Device Category, etc.), not just page-level dimensions.

Important: the maxScrollTracker plugin works best on pages whose height doesn't change once the page has loaded. It is not recommended to use maxScrollTracker on pages that use techniques like infinite scroll.

Usage

To enable the maxScrollTracker plugin, run the require command, specify the plugin name 'maxScrollTracker', and pass in any configuration options (if any) you wish to set:

ga('require', 'maxScrollTracker', options);

Using a custom metric

The easiest way to track max scroll percentage is to create a custom metric called Max Scroll Percentage that you set in your plugin configuration options, and then to create a calculated metric Avg. Max Scroll Percentage that you use in your reports.

Since the max scroll tracker plugin only reports a single max scroll percentage per unique page path per session, you can calculate the average max scroll percentage for any dimension by dividing the value of your Max Scroll Percentage custom metric by the Unique Pageviews metrics. Here's what the formula looks like:

{{Max Scroll Percentage}} / ( 100 * {{Unique Pageviews}} )

The screenshot in the overview shows some examples of what reports with these custom and calculated metrics look like.

Options

The following table outlines all possible configuration options for the maxScrollTracker plugin. If any of the options has a default value, the default is explicitly stated:

Name	Type	Description
increaseThreshold	number	The minimum increase in max scroll percentage that must occur before an event is sent. For example, if the current, stored max scroll percentage for a particular page is 45 and the increaseThreshold is 10, no max scroll increase events will be sent until the user scrolls to at least 55% down the current page. . Default: 20
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).
maxScrollMetricIndex	number	If set, a custom metric at the index provided is sent with all increase events. The metric value is set to the same value as the event value (the max scroll percentage increase amount).
fieldsObj	Object	See the common options guide for the fieldsObj description.
hitFilter	Function	See the common options guide for the hitFilter description.

Default field values

The maxScrollTracker 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	'Max Scroll'
eventAction	'increase'
eventLabel	scrollPercentage
eventValue	increaseAmount
nonInteraction	true

Note: the reference to increaseAmount refers to the amount the max scroll percentage has increased since the previous event. The reference to scrollPercentage refers to the current scroll percentage for the page.

Methods

The following table lists all methods for the maxScrollTracker plugin:

Name	Description
remove	Removes the maxScrollTracker 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.

Examples

Setting a session timeout and time zone

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',
});

Making scroll events interactive beyond 50%

By default, all events sent by this plugin are non-interaction events, which means they won't affect your bounce rate. However, in some cases you may want to consider scrolling beyond a specific point an engagement and not a bounce.

This example shows how to use the hitFilter option to send max scroll events as interactive once the user has scrolled more than 50%.

ga('require', 'maxScrollTracker', {
  hitFilter: function(model) {
    var scrollPercentage = model.get('eventLabel');
    if (scrollPercentage > 50) {
      // Sets the nonInteractive field to `false` for the current hit.
      model.set('nonInteraction', false, true);
    }
  },
});

Setting a custom metric

If you want to create a calculated metric to more easily report on max scroll events, you'll need to also create a custom metric and set the index of that custom metric when requiring the maxScrollTracker plugin:

ga('require', 'maxScrollTracker', {
  maxScrollMetricIndex: 1,
});

Note: this requires creating a custom metric in your Google Analytics property settings and creating a calculated metric in your Google Analytics view settings.