impression-tracker.md

impressionTracker

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

Overview

The impressionTracker plugin allows you to specify a list of elements and then track whether any of those elements are visible within the browser viewport. If any of the elements are not visible, an event is sent to Google Analytics as soon as they become visible.

Impression tracking is useful for getting a more accurate sense of whether particular advertisements or call-to-action elements were seen by the user.

Usage

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

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

Browser support

The impressionTracker plugin takes advantage of a new browser API called IntersectionObserver, which allows you to register a callback that gets invoked whenever a target element is visible within the viewport.

The IntersectionObserver API is supported natively in Chrome 51+, and with an IntersectionObserver polyfill, it can be used in all other browsers as well.

To use the polyfill, add it to your page prior to requiring the impressionTracker plugin:

The IntersectionObsever polyfill is available on npm, and can be installed by running the following command:

npm install intersection-observer

Then link to the intersection-observer.js script file in your HTML page:

<script src="path/to/intersection-observer.js"></script>

The IntersectionObsever polyfill is also available from polyfill.io. An advantage of using polyfill.io is the service automatically detects browser support and only delivers the polyfill (and any needed dependencies) if the requesting brower lacks native support.

You can link to the CDN version on polyfill.io with the following script:

<script src="https://cdn.polyfill.io/v2/polyfill.min.js?features=IntersectionObserver"></script>

See the polyfill.io documentation for more information on using the service.

Options

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

Name	Type	Description
elements	Array<string|Object>	A list of element IDs or element objects. See the element object properties section below for details.
rootMargin	string	A CSS margin string accepting pixel or percentage values. It is passed as the rootMargin option to the IntersectionObserver instance, which is used to expand or contract the viewport area to change when an element is considered visible. For example: the string '-20px 0px' would contract the viewport by 20 pixels on the top and bottom sides, and all element visibility calculations would be based on that rather than the full viewport dimensions.
fieldsObj	Object	See the common options guide for the fieldsObj description.
attributePrefix	string	See the common options guide for the attributePrefix description. Default: 'ga-'
hitFilter	Function	See the common options guide for the hitFilter description.

element object properties

Name	Type	Description
id	string	The ID attribute of the element to track.
threshold	number	A percentage of the element's area that must be within the viewport in order for the element to be considered visible. This value is used as one of the thresholds passed to the IntersectionObserver instance. A threshold of 1 means the element must be entirely within the viewport to be considered visible. A threshold of 0.5 means half of the element must be within the viewport. And a threshold of 0 means if any of the element intersects with the viewport at all (including just the border), it is considered visible. Default: 0
trackFirstImpressionOnly	boolean	When true, an impression for this element is only tracked the first time it is visible within the viewport. Set this to false if you want to track subsequent impressions. Default: true

Default field values

The impressionTracker plugin sets the following default field values on all hits it sends. To customize these values, use one of the options described above, or set the field value declaratively as an attribute in the HTML.

Field	Value
hitType	'event'
eventCategory	'Viewport'
eventAction	'impression'
eventLabel	element.id
nonInteraction	true

Note: the reference to element in the table above refers to the element being observed.

Methods

The following table lists all methods for the impressionTracker plugin:

Name	Description
observeElements	Accepts an array of elements (as described in the options section) to start observing for impressions.
unobserveElements	Accepts an array of elements (as described in the options section) to stop observing for impressions. (Note: elements whose trackFirstImpressionOnly property is true are automatically unobserved after the first impression.)
unobserveAllElements	Stops observing all elements currently being observed.
remove	Removes the impressionTracker plugin from the specified tracker, disconnects all observers, 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

Basic tracking of when elements are visible

This example sends an event when any part of the #foo and/or #bar elements become visible in the viewport:

ga('require', 'impressionTracker', {
  elements: ['foo', 'bar']
});

Using threshold values

This example only sends events when the #foo and/or #bar element are at least half-way visible in the viewport:

ga('require', 'impressionTracker', {
  elements: [
    {
      id: 'foo',
      threshold: 0.5
    },
    {
      id: 'bar',
      threshold: 0.5
    }
  ]
});

Tracking multiple impressions for the same element

This example sends events anytime the #foo and/or #bar elements become visible in the viewport. Then, if the #foo and/or #bar elements leave the viewport and become visible again later, another event is sent for each occurrence.

ga('require', 'impressionTracker', {
  elements: [
    {
      id: 'foo',
      trackFirstImpressionOnly: false
    },
    {
      id: 'bar',
      trackFirstImpressionOnly: false
    }
  ]
});

Change the rootMargin value

This example sends events anytime the #foo and/or #bar elements appear at least within 20 pixels of the top and bottom edges of the viewport.

ga('require', 'impressionTracker', {
  elements: ['foo', 'bar'],
  rootMargin: '-20px 0'
});

Programmatically observing and unobserving elements

This example requires the impressionTracker plugin without specifying any elements to observe. When the user clicks on the #start-observing button, observation starts on the #foo element. When the user clicks on the #stop-observing button, observing #foo stops.

ga('require', 'impressionTracker');

var startObservingBtn = document.getElementById('start-observing');
var stopObservingBtn = document.getElementById('stop-observing');

startObservingBtn.addEventListener('click', function() {
  ga('impressionTracker:observeElements', ['foo']);
});

stopObservingBtn.addEventListener('click', function() {
  ga('impressionTracker:unobserveElements', ['foo']);
});