5.9 KiB
Event Tracking
We use Snowplow for tracking custom events.
Generic tracking function
In addition to Snowplow's built-in method for tracking page views, we use a generic tracking function which enables us to selectively apply listeners to events.
The generic tracking function can be imported in EE-specific JS files as follows:
import { trackEvent } from `ee/stats`;
This gives the user access to the trackEvent
method, which takes the following parameters:
parameter | type | description | required |
---|---|---|---|
category |
string | Describes the page that you're capturing click events on. Unless infeasible, please use the Rails page attribute document.body.dataset.page by default. |
true |
eventName |
string | Describes the action the user is taking. The first word should always describe the action. For example, clicks should be click and activations should be activate . Use underscores to describe what was acted on. For example, activating a form field would be activate_form_input . Clicking on a dropdown is click_dropdown . |
true |
additionalData |
object | Additional data such as label , property , and value as described in our Feature Instrumentation taxonomy. |
false |
Read more about instrumentation and the taxonomy in the Product Handbook.
Tracking in .js
and .vue
files
The most simple use case is to add tracking programmatically to an event of interest in Javascript.
The following example demonstrates how to track a click on a button in Javascript by calling the trackEvent
method explicitly:
import { trackEvent } from `ee/stats`;
trackEvent('dashboard:projects:index', 'click_button', {
label: 'create_from_template',
property: 'template_preview',
value: 'rails',
});
Tracking in HAML templates
Sometimes we want to track clicks for multiple elements on a page. Creating event handlers for all elements could soon turn into a tedious task.
There's a more convenient solution to this problem. When working with HAML templates, we can add data-track-*
attributes to elements of interest. This way, all elements that have both data-track-label
and data-track-event
attributes assigned get marked for event tracking. All we have to do is call the bindTrackableContainer
method on a container which allows for better scoping.
Below is an example of data-track-*
attributes assigned to a button in HAML:
%button.btn{ data: { track_label: "create_from_template", track_property: "template_preview", track_event: "click_button", track_value: "my-template" } }
By calling bindTrackableContainer('.my-container')
, click handlers get bound to all elements located in .my-container
provided that they have the necessary data-track-*
attributes assigned to them.
import Stats from 'ee/stats';
document.addEventListener('DOMContentLoaded', () => {
Stats.bindTrackableContainer('.my-container', 'category');
});
The second parameter in bindTrackableContainer
is optional. If omitted, the value of document.body.dataset.page
will be used as category instead.
Below is a list of supported data-track-*
attributes:
attribute | description | required |
---|---|---|
data-track-label |
The label in trackEvent |
true |
data-track-event |
The eventName in trackEvent |
true |
data-track-property |
The property in trackEvent . If omitted, an empty string will be used as a default value. |
false |
data-track-value |
The value in trackEvent . If omitted, this will be target.value or empty string. For checkboxes, the default value being tracked will be the element's checked attribute if data-track-value is omitted. |
false |
Since Snowplow is an Enterprise Edition feature, it's necessary to create a CE backport when adding data-track-*
attributes to HAML templates in most cases.