Tracker endeavors to be a convenient packager for your event tracking needs no matter what analytics platform you use. It includes "channels" for Google Analytics, Google Tag Manager, and Console output (helpful for debugging) by default and it's easy to add your own for other services.
Tracker uses the provided event object to standardize the values submitted to Google Analytics for more consistent event tracking. In addition a custom event name can be provided that can be triggered in the tracker callback.
The tracker object can contain the following properties (with recommended values).
type - String value of the type of event: link_click, form_submission, etc.
identifier - A string identifier or an object made up of separate values.
- Identifier Object Properties: dom_data, dom_id, dom_name.
target - String of the target, commonly link url, or form action
value - The event value
When using an object for the identifier the properties will be applied to the label in order: dom_data, dom_id, dom_name to standardize label creation.
Include the module in your project:
$ npm install @flickerbox/tracker
import Tracker from '@flickerbox/tracker';
var tracker = new Tracker();
The constructor supports optional overrides for the following settings:
timeout (default: 500) - Value for the amount of time (in ms) to wait before forcing the complete event.
trackerChannel (default: GA) - Which method (GA/GTM) to use when submitting the event.
- 1 - Use Google Analytics gtag() method (for ga() see legacy instructions below)
- 2 - Use Google Tag Manager dataLayer.push() method
tracker = new Tracker({tracker_method: 2})
A sample custom channel is included to output event data to the browser console. It can be used as a template for your own custom channel or used for debugging during development.
import Tracker from '@flickerbox/tracker'
import ConsoleOutput from "@flickerbox/tracker/src/channels/console";
let tracker = new Tracker({
trackerChannel: ConsoleOutput
});
Use of tracker with Google Tag Manager requires a few tags/variables to be configured.
Use the included template file to import these assets to your Google Tag Manager container.
When using GTM for event tracking the following data layer variables are required.
- ga_category - Tag Event Category
- ga_action - Tag Event Action
- ga_label - Tag Event Label
- ga_value - Tag Event Value
- Google Analytics ID - Tracking ID
- ga_event_tracking - Custom Event Trigger
- Global Event Tracking - Google Analytics Universal Analytics Tag
In addition, a Universal Analytics tag with an Event track type should be added using these variables.
The following examples illustrate how to add event tracking using a variety of jQuery event listeners, however, jQuery is not required.
$('body').on('click', 'a', function(event) {
var clicked = $(this),
link = clicked.attr('href'),
target = link;
// not all links need to be forwarded after tracking, but some do
if (clicked.attr('target') !== '_blank' &&
typeof link != 'undefined' &&
link.indexOf('javascript:') !== 0 &&
link.indexOf('#') !== 0
) {
event.preventDefault();
$(document).one('track_complete', function() {
window.location.href = link;
});
}
tracker.event(
{
type: "link_click",
identifier: {
dom_data: clicked.attr('data-event'),
dom_id: clicked.attr('id')
},
target: link
},
'track_complete'
);
});
$('#my_form').on('submit', function(event){
tracker.event(
{
type: "form_submission",
identifier: {
dom_data: $(this).attr('data-event'),
dom_id: $(this).attr('id'),
dom_name: $(this).attr('action')
},
target: $(this).attr('src')
}
);
});
$('img').on('click', function(event) {
if (!$(this).parent().is('a')) {
tracker.event(
{
type: "image_click",
identifier: {
dom_data: $(this).attr('data-event'),
dom_id: $(this).attr('id'),
dom_name: $(this).attr('alt')
},
target: $(this).attr('src')
}
);
}
});
From v2.1.0 tracker supports Google Analytics event tracking through both Universal Analytics ga('send', 'event'...) and Global Site Tag gtag('event'...). Which you need depends on how you've added Google Analytics to your site.
If your site uses global site tag you should use the tracker defaults. Global Site Tag is the default implementation for the GoogleAnalytics channel, and the default tracker channel, from v2.1.0+. Your global site tag implementation will look similar to:
<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'GA_MEASUREMENT_ID');
</script>
If your site uses analytics.js you should use the "legacy" channel. This implementation will look similar to:
<!-- Google Analytics -->
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-XXXXX-Y', 'auto');
ga('send', 'pageview');
</script>
<!-- End Google Analytics -->
When adding the tracker to your site you should import the legacy channel and use it in your tracker config. Which will look something like:
import GoogleAnalyticsLegacy from "@flickerbox/tracker/src/channels/google-analytics-legacy"
const tracker = new Tracker({
trackerChannel: GoogleAnalyticsLegacy,
})
tracker_method config property should be changed to trackerChannel. Values of 1 (Google Analytics) and 2 (Google Tag Manager) are still supported for this property.
let tracker = new Tracker({
tracker_method: 2)
});
let tracker = new Tracker({
trackerChannel: 2)
});
identifier properties should be changed to camelCase
tracker.event(
{
type: "other_click",
identifier: {
dom_data: $(this).attr('data-event'),
dom_id: $(this).attr('id'),
dom_name: $(this).attr('alt')
},
target: $(this).attr('src')
}
tracker.event(
{
type: "other_click",
identifier: {
domData: $(this).attr('data-event'),
domId: $(this).attr('id'),
domName: $(this).attr('alt')
},
target: $(this).attr('src')
}
If your site needs the Google Analytics channel but you haven't yet updated to the Global Site Tag you should use the "legacy" Google Analytics channel in the tracker module when upgrading to v2.1.0+. Instructions for using the legacy channel are available above.