gitlab-org--gitlab-foss/doc/development/fe_guide/event_tracking.md
Simon Knox d7c92faacb Cleanup of fe_docs
Start moving back to regular fe_docs
Remove Initiatives, add section to index in fe_guide
Delete some no-longer-relevant parts from principles
Update title - Progressive Enchancement is a browser-support term
and could be confused
"When to use" parts are discussed elswhere
Vue & jQuery issue is no longer relevant
Delete duplicate Security docs
Remove empty files, move event_tracking
Shuffle index sections around
Remove sections on Vue & Webpack (we say same thing in prev paragraph)
Remove link to Droplab docs
2019-03-22 09:24:10 +11:00

6.5 KiB

Event Tracking

We use Snowplow for tracking custom events (available in GitLab Enterprise Edition only).

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.

Testing

Snowplow can be enabled by navigating to:

  • Admin area > Settings > Integrations in the UI.
  • admin/application_settings/integrations in your browser.

The following configuration is required:

Name Value
Collector snowplow.trx.gitlab.net
Site ID gitlab
Cookie domain .gitlab.com

Now the implemented tracking events can be inspected locally by looking at the network panel of the browser's development tools.