debian-mirror-gitlab/doc/development/fe_guide/event_tracking.md

89 lines
4.6 KiB
Markdown
Raw Normal View History

2019-10-12 21:52:04 +05:30
# Event tracking
2019-07-07 11:18:12 +05:30
2019-10-12 21:52:04 +05:30
GitLab provides `Tracking`, an interface that wraps
[Snowplow](https://github.com/snowplow/snowplow) for tracking custom events.
It uses Snowplow's custom event tracking functions.
2019-07-07 11:18:12 +05:30
2019-10-12 21:52:04 +05:30
The tracking interface can be imported in JS files as follows:
2019-07-07 11:18:12 +05:30
```javascript
2019-10-12 21:52:04 +05:30
import Tracking from `~/tracking`;
2019-07-07 11:18:12 +05:30
```
2019-10-12 21:52:04 +05:30
## Tracking in HAML or Vue templates
2019-07-07 11:18:12 +05:30
2019-10-12 21:52:04 +05:30
To avoid having to do create a bunch of custom javascript event handlers, when working within HAML or Vue templates, we can add `data-track-*` attributes to elements of interest. This way, all elements that have a `data-track-event` attribute to automatically have event tracking bound.
2019-07-07 11:18:12 +05:30
2019-10-12 21:52:04 +05:30
Below is an example of `data-track-*` attributes assigned to a button in HAML:
2019-07-07 11:18:12 +05:30
2019-10-12 21:52:04 +05:30
```haml
%button.btn{ data: { track_event: "click_button", track_label: "template_preview", track_property: "my-template", track_value: "" } }
```
2019-07-07 11:18:12 +05:30
2019-10-12 21:52:04 +05:30
We can then setup tracking for large sections of a page, or an entire page by telling the Tracking interface to bind to it.
2019-07-07 11:18:12 +05:30
```javascript
2019-10-12 21:52:04 +05:30
import Tracking from '~/tracking';
2019-07-07 11:18:12 +05:30
2019-10-12 21:52:04 +05:30
// for the entire document
new Tracking().bind();
// for a container element
document.addEventListener('DOMContentLoaded', () => {
new Tracking('my_category').bind(document.getElementById('my-container'));
2019-07-07 11:18:12 +05:30
});
2019-10-12 21:52:04 +05:30
2019-07-07 11:18:12 +05:30
```
2019-10-12 21:52:04 +05:30
When you instantiate a Tracking instance you can provide a category. If none is provided, `document.body.dataset.page` will be used. When you bind the Tracking instance you can provide an element. If no element is provided to bind to, the `document` is assumed.
2019-07-07 11:18:12 +05:30
2019-10-12 21:52:04 +05:30
Below is a list of supported `data-track-*` attributes:
2019-07-07 11:18:12 +05:30
2019-10-12 21:52:04 +05:30
| attribute | required | description |
|:----------------------|:---------|:------------|
| `data-track-event` | true | Action the user is taking. Clicks should be `click` and activations should be `activate`, so for example, focusing a form field would be `activate_form_input`, and clicking a button would be `click_button`. |
| `data-track-label` | false | The `label` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/feature-instrumentation/#taxonomy). |
| `data-track-property` | false | The `property` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/feature-instrumentation/#taxonomy). |
| `data-track-value` | false | The `value` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/feature-instrumentation/#taxonomy). If omitted, this will be the elements `value` property or an empty string. For checkboxes, the default value will be the element's checked attribute or `false` when unchecked. |
2019-07-07 11:18:12 +05:30
2019-10-12 21:52:04 +05:30
## Tracking in raw Javascript
2019-07-07 11:18:12 +05:30
2019-10-12 21:52:04 +05:30
Custom events can be tracked by directly calling the `Tracking.event` static function, which accepts the following arguments:
| argument | type | default value | description |
|:-----------|:-------|:---------------------------|:------------|
| `category` | string | document.body.dataset.page | Page or subsection of a page that events are being captured within. |
| `event` | string | 'generic' | Action the user is taking. Clicks should be `click` and activations should be `activate`, so for example, focusing a form field would be `activate_form_input`, and clicking a button would be `click_button`. |
| `data` | object | {} | Additional data such as `label`, `property`, and `value` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/feature-instrumentation/#taxonomy). These will be set as empty strings if you don't provide them. |
2019-07-07 11:18:12 +05:30
2019-10-12 21:52:04 +05:30
Tracking can be programmatically added to an event of interest in Javascript, and the following example demonstrates tracking a click on a button by calling `Tracking.event` manually.
2019-07-07 11:18:12 +05:30
```javascript
2019-10-12 21:52:04 +05:30
import Tracking from `~/tracking`;
2019-07-07 11:18:12 +05:30
2019-10-12 21:52:04 +05:30
document.getElementById('my_button').addEventListener('click', () => {
Tracking.event('dashboard:projects:index', 'click_button', {
label: 'create_from_template',
property: 'template_preview',
value: 'rails',
});
})
2019-07-07 11:18:12 +05:30
```
2019-10-12 21:52:04 +05:30
## Toggling tracking on or off
2019-07-07 11:18:12 +05:30
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.