Many of the autotrack plugins accept options that are common to multiple different plugins. The following common options are documented in this guide:
Some of the autotrack plugins send hits with default analytics.js field values set. These plugins accept a fieldsObj
option, which allows you to customize those values for each plugin. It also allows you to set any fields that aren't set by default.
The fieldsObj
option is an Object
whose properties can be any analytics.js field name, and whose values will be used as the corresponding field value for all hits sent by the plugin.
This configuration ensures all events sent by the mediaQueryTracker
plugin are non-interaction events events:
ga('require', 'mediaQueryTracker', {
definitions: [...],
fieldsObj: {
nonInteraction: true
}
});
This configuration sets a custom dimension at index 1 for all pageview hits sent by the urlChangeTracker
. This would allow you to differentiate between the initial pageview and "virtual" pageviews sent after loading new pages via AJAX:
ga('require', 'urlChangeTracker', {
fieldsObj: {
dimension1: 'virtual'
}
});
ga('send', 'pageview', {
dimension1: 'pageload'
});
All plugins that send hits to Google Analytics as a result of user interactions with DOM elements support declarative attribute binding (see the eventTracker
plugin to see how this works). As such, each of these plugins accept an attributePrefix
option to customize what attribute prefix to use.
By default, the attributePrefix
value used by each plugin is the string 'ga-'
, though that value can be customized on a per-plugin basis.
Note: when setting the same field in both the fieldsObj
option as well as via a DOM element attribute, the attribute's value will override the fieldsObj
value.
ga('require', 'eventTracker', {
attributePrefix: 'data-'
});
<button
data-on="click"
data-event-category="Video"
data-event-action="play">
Play video
</button>
ga('require', 'impressionTracker', {
elements: ['cta'],
attributePrefix: 'data-ga'
});
<div
id="cta"
data-ga-event-category="Call to action"
data-ga-event-action="seen">
Call to action
</a>
ga('require', 'outboundLinkTracker', {
attributePrefix: ''
});
<a href="https://example.com" event-category="External Link">Click</a>
The hitFilter
option is useful when you need to make more advanced modifications to a hit, or when you need to abort the hit altogether. hitFilter
is a function that gets invoked with the tracker's model object as its first argument, and (if the hit was initiated by a user interaction with a DOM element) the DOM element as the second argument.
Within the hitFilter
function you can get the value of any of the model object's fields using the get
method on the model
argument. And you can set a new value using the set
method on the model
argument. To abort the hit, throw an error.
To modify the model for the current hit only (and not all subsequent hits), make sure to set the third argument (temporary
) to true
.
The hitFilter
option works by overriding the tracker's buildHitTask
. The passed hitFilter
function runs after the fieldsObj
values and attribute fields have been set on the tracker but before running the original buildHitTask
. Refer to the guide on analytics.js tasks to learn more.
This configuration sets custom dimension 1 to whatever the eventValue
field is set to for all visibilitychange
event hits. It specifies true
as the third argument to the set
method, so this change affects the current hit only:
ga('require', 'pageVisibilityTracker', {
hitFilter: function(model) {
model.set('dimension1', String(model.get('eventValue')), true);
}
});
This configuration prevents hits from being sent for impressions on elements with the is-invisible
class.
ga('require', 'impressionTracker', {
hitFilter: function(model, element) {
if (element.className.indexOf('is-invisible') > -1) {
throw new Error('Aborting hit');
}
}
});