media-query-tracker.md

mediaQueryTracker

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

Overview

Most sites today use responsive design to update the page layout based on the screen size or capabilities of the user's device. If media queries are used to alter the look or functionality of a page, it's important to capture that information to better understand how usage differs when different media queries are active.

The mediaQueryTracker plugin allows you to register the set of media query values you're using, and those values are automatically tracked via custom dimensions with each hit. It also sends events when those values change.

Usage

To enable the mediaQueryTracker plugin, run the require command, specify the plugin name 'mediaQueryTracker', and pass in the configuration options you want to set:

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

The options object requires a list of media query definitions that must specify a custom dimension index. Custom dimensions can be created in your property settings in Google Analytics. The following section explains how.

Setting up custom dimensions in Google Analytics

1. Log in to Google Analytics, choose the account and property you're sending data too, and create a custom dimension for each set of media queries you want to track (e.g. Breakpoints, Resolution/DPI, Device Orientation)
2. Give each dimension a name (e.g. Breakpoints), select a scope of hit, and make sure the "active" checkbox is checked.
3. In the definitions config object, set the name and dimensionIndex values to be the same as the name and index shown in Google Analytics.

Refer to the definition object documentation for an example.

Options

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

Name	Type	Description
definitions	Object|Array<Object>	A definition object or an array of definition objects. See the definition object description for property details.
changeTemplate	Function	The changeTemplate function (via its return value) determines what the eventLabel field will be for event hits when the matching media definition changes. The function is invoked with the newly matching value and the previously matching value as its first and second arguments, respectively: Default: function(newValue, oldValue) { return oldValue + ' => ' + newValue; }
changeTimeout	number	The debounce timeout, i.e., the amount of time to wait before sending the change event. If multiple change events occur within the timeout period, only the last one is sent. Default: 1000
fieldsObj	Object	See the common options guide for the fieldsObj description.
hitFilter	Function	See the common options guide for the hitFilter description.

The definition object

The definition object allows you to group multiple different types of media queries together to be tracked by the same custom dimension.

Name	Type	Description
name	string	A unique name that will be used as the eventCategory value for media query change events.
dimensionIndex	number	The index of the custom dimension created in Google Analytics.
items	Array	An array of item objects. See the item object description for property details.

The item object

The item object allows you to specify what media query values are relevant within each definition group.

Name	Type	Description
name	string	The value that will be set on the custom dimension at the specified index.
media	string	The media query value to test for a match.

Note: if multiple media values match at the same time, the one specified later in the items array will take precedence.

Default field values

The mediaQueryTracker plugin sets the following default field values on all hits it sends. To customize these values, use one of the options described above.

Field	Value
hitType	'event'
eventCategory	definition.name
eventAction	'change'
eventLabel	options.changeTemplate()

Note: the reference to definition in the table above refers to the definition the changing media value is defined in. The reference to options refers to passed configuration options.

Methods

The following table lists all methods for the mediaQueryTracker plugin:

Name	Description
remove	Removes the mediaQueryTracker plugin from the specified tracker, removes all media query listeners, 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.

Example

Basic usage

This example requires the mediaQueryTracker plugin and customizes it to track breakpoint, resolution, and orientation media query data:

ga('require', 'mediaQueryTracker', {
  definitions: [
    {
      name: 'Breakpoint',
      dimensionIndex: 1,
      items: [
        {name: 'sm', media: 'all'},
        {name: 'md', media: '(min-width: 30em)'},
        {name: 'lg', media: '(min-width: 48em)'}
      ]
    },
    {
      name: 'Resolution',
      dimensionIndex: 2,
      items: [
        {name: '1x',   media: 'all'},
        {name: '1.5x', media: '(min-resolution: 144dpi)'},
        {name: '2x',   media: '(min-resolution: 192dpi)'}
      ]
    },
    {
      name: 'Orientation',
      dimensionIndex: 3,
      items: [
        {name: 'landscape', media: '(orientation: landscape)'},
        {name: 'portrait',  media: '(orientation: portrait)'}
      ]
    }
  ]
});

Customizing the change template and timeout

This code updates the change template to only report the new media value in the event hit. It also increases the debounce timeout amount for change events, so rapid changes have more time to settle before being reported:

ga('require', 'mediaQueryTracker', {
  definitions: [
    {
      name: 'Breakpoint',
      dimensionIndex: 1,
      items: [
        {name: 'sm', media: 'all'},
        {name: 'md', media: '(min-width: 30em)'},
        {name: 'lg', media: '(min-width: 48em)'}
      ]
    }
  ],
  changeTemplate: function(newValue, oldValue) {
    return newValue;
  },
  changeTimeout: 3000
});