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