diff options
Diffstat (limited to 'doc/development/snowplow/implementation.md')
| -rw-r--r-- | doc/development/snowplow/implementation.md | 168 |
1 files changed, 104 insertions, 64 deletions
diff --git a/doc/development/snowplow/implementation.md b/doc/development/snowplow/implementation.md index 439485c9e73..d35413cfd5f 100644 --- a/doc/development/snowplow/implementation.md +++ b/doc/development/snowplow/implementation.md @@ -18,21 +18,27 @@ to track custom events. For the recommended frontend tracking implementation, see [Usage recommendations](#usage-recommendations). +Structured events and page views include the [`gitlab_standard`](schemas.md#gitlab_standard) +context, using the `window.gl.snowplowStandardContext` object which includes +[default data](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/views/layouts/_snowplow.html.haml) +as base. This object can be modified for any subsequent structured event fired, +although it's not recommended. + Tracking implementations must have an `action` and a `category`. You can provide additional -categories from the [structured event taxonomy](index.md#structured-event-taxonomy) with an `extra` object -that accepts key-value pairs. +properties from the [structured event taxonomy](index.md#structured-event-taxonomy), in +addition to an `extra` object that accepts key-value pairs. -| Field | Type | Default value | Description | +| Property | Type | Default value | Description | |:-----------|:-------|:---------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `category` | string | `document.body.dataset.page` | Page or subsection of a page in which events are captured. | -| `action` | string | generic | Action the user is taking. Clicks must be `click` and activations must be `activate`. For example, focusing a form field is `activate_form_input`, and clicking a button is `click_button`. | -| `data` | object | `{}` | Additional data such as `label`, `property`, `value`, `context` as described in [Structured event taxonomy](index.md#structured-event-taxonomy), and `extra` (key-value pairs object). | +| `action` | string | `'generic'` | Action the user is taking. Clicks must be `click` and activations must be `activate`. For example, focusing a form field is `activate_form_input`, and clicking a button is `click_button`. | +| `data` | object | `{}` | Additional data such as `label`, `property`, `value` as described in [Structured event taxonomy](index.md#structured-event-taxonomy), `context` for custom contexts, and `extra` (key-value pairs object). | ### Usage recommendations - Use [data attributes](#implement-data-attribute-tracking) on HTML elements that emit `click`, `show.bs.dropdown`, or `hide.bs.dropdown` events. -- Use the [Vue mixin](#implement-vue-component-tracking) for tracking custom events, or if the supported events for data attributes are not propagating. -- Use the [tracking class](#implement-raw-javascript-tracking) when tracking raw JavaScript files. +- Use the [Vue mixin](#implement-vue-component-tracking) for tracking custom events, or if the supported events for data attributes are not propagating. For example, clickable components that don't emit `click`. +- Use the [tracking class](#implement-raw-javascript-tracking) when tracking in vanilla JavaScript files. ### Implement data attribute tracking @@ -42,6 +48,9 @@ The following example shows `data-track-*` attributes assigned to a button: ```haml %button.btn{ data: { track: { action: "click_button", label: "template_preview", property: "my-template" } } } + +// or +// %button.btn{ data: { track_action: "click_button", track_label: "template_preview", track_property: "my-template" } } ``` ```html @@ -62,7 +71,7 @@ The following example shows `data-track-*` attributes assigned to a button: | `data-track-property` | false | Any additional property of the element, or object being acted on. | | `data-track-value` | false | Describes a numeric value (decimal) directly related to the event. This could be the value of an input. For example, `10` when clicking `internal` visibility. If omitted, this is the element's `value` property or `undefined`. For checkboxes, the default value is the element's checked attribute or `0` when unchecked. | | `data-track-extra` | false | A key-value pair object passed as a valid JSON string. This attribute is added to the `extra` property in our [`gitlab_standard`](schemas.md#gitlab_standard) schema. | -| `data-track-context` | false | The `context` as described in our [Structured event taxonomy](index.md#structured-event-taxonomy). | +| `data-track-context` | false | To append a custom context object, passed as a valid JSON string. | #### Event listeners @@ -74,12 +83,19 @@ If click events stop propagating, you must implement listeners and [Vue componen #### Helper methods -Use the following Ruby helper: +You can use the following Ruby helper: ```ruby tracking_attrs(label, action, property) # { data: { track_label... } } +``` +You can also use it on HAML templates: + +```haml %button{ **tracking_attrs('main_navigation', 'click_button', 'navigation') } + +// When adding additional data +// %button{ data: { platform: "...", **tracking_attrs('main_navigation', 'click_button', 'navigation') } } ``` If you use the GitLab helper method [`nav_link`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/helpers/tab_helper.rb#L76), you must wrap `html_options` under the `html_options` keyword argument. If you @@ -91,7 +107,7 @@ use the `ActionView` helper method [`link_to`](https://api.rubyonrails.org/v5.2. track_action: "click_button" }) # Good -= nav_link(controller: ['dashboard/groups', 'explore/groups'], html_options: { data: { track_label: += nav_link(controller: ['dashboard/groups', 'explore/groups'], html_options: { data: { track_label: "explore_groups", track_action: "click_button" } }) # Good (other helpers) @@ -101,63 +117,64 @@ track_action: "click_button" }) ### Implement Vue component tracking -For custom event tracking, use a Vue `mixin` in components. Vue `mixin` exposes the `Tracking.event` -static method and the `track` method. You can specify tracking options in `data` or `computed`. -These options override any defaults and allow the values to be dynamic from props or based on state. - -Several default options are passed when an event is tracked from the component: +For custom event tracking, use the [Vue mixin](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/tracking/tracking.js#L207). It exposes `Tracking.event` as the `track` method. +You can specify tracking options by creating a `tracking` data object or +computed property, and as a second parameter: `this.track('click_button', opts)`. +These options override any defaults and allow the values to be dynamic from props or based on state: -- `category`: If you don't specify, by default `document.body.dataset.page` is used. -- `label` -- `property` -- `value` +| Property | Type | Default | Example | +| -- | -- | -- | -- | +| `category` | string | `document.body.dataset.page` | `'code_quality_walkthrough'` | +| `label` | string | `''` | `'process_start_button'` | +| `property` | string | `''` | `'asc'` or `'desc'` | +| `value` | integer | `undefined` | `0`, `1`, `500` | +| `extra` | object | `{}` | `{ selectedVariant: this.variant }` | To implement Vue component tracking: -1. Import the `Tracking` library and request a `mixin`: +1. Import the `Tracking` library and call the `mixin` method: ```javascript import Tracking from '~/tracking'; - const trackingMixin = Tracking.mixin; - ``` -1. Provide categories to track the event from the component. For example, to track all events in a -component with a label, use the `label` category: + const trackingMixin = Tracking.mixin(); - ```javascript - import Tracking from '~/tracking'; - const trackingMixin = Tracking.mixin({ label: 'right_sidebar' }); + // Optionally provide default properties + // const trackingMixin = Tracking.mixin({ label: 'right_sidebar' }); ``` -1. In the component, declare the Vue `mixin`: +1. Use the mixin in the component: ```javascript export default { mixins: [trackingMixin], - // ...[component implementation]... + // Or + // mixins: [Tracking.mixin()], + // mixins: [Tracking.mixin({ label: 'right_sidebar' })], + data() { return { expanded: false, - tracking: { - label: 'left_sidebar', - }, }; }, }; ``` -1. To receive event data as a tracking object or computed property: - - Declare it in the `data` function. Use a `tracking` object when default event properties are dynamic or provided at runtime: +1. You can specify tracking options in by creating a `tracking` data object +or computed property: ```javascript export default { name: 'RightSidebar', + mixins: [Tracking.mixin()], + data() { return { + expanded: false, + variant: '', tracking: { label: 'right_sidebar', - // category: '', // property: '', // value: '', // experiment: '', @@ -165,18 +182,28 @@ component with a label, use the `label` category: }, }; }, + + // Or + // computed: { + // tracking() { + // return { + // property: this.variant, + // extra: { expanded: this.expanded }, + // }; + // }, + // }, }; ``` - - Declare it in the event data in the `track` function. This object merges with any previously provided options: +1. Call the `track` method. Tracking options can be passed as the second parameter: - ```javascript - this.track('click_button', { - label: 'right_sidebar', - }); - ``` + ```javascript + this.track('click_button', { + label: 'right_sidebar', + }); + ``` -1. Optional. Use the `track` method in a template: + Or use the `track` method in the template: ```html <template> @@ -185,55 +212,67 @@ component with a label, use the `label` category: <div v-if="expanded"> <p>Hello world!</p> - <button @click="track('click_action')">Track another event</button> + <button @click="track('click_button')">Track another event</button> </div> </div> </template> ``` -The following example shows an implementation of Vue component tracking: +#### Testing example ```javascript export default { - name: 'RightSidebar', - mixins: [Tracking.mixin({ label: 'right_sidebar' })], + name: 'CountDropdown', + + mixins: [Tracking.mixin({ label: 'count_dropdown' })], + data() { return { - expanded: false, + variant: 'counter', + count: 0, }; }, + methods: { - toggle() { - this.expanded = !this.expanded; - // Additional data will be merged, like `value` below - this.track('click_toggle', { value: Number(this.expanded) }); - } - } + handleChange({ target }) { + const { variant } = this; + + this.count = Number(target.value); + + this.track('change_value', { + value: this.count, + extra: { variant } + }); + }, + }, }; ``` -#### Testing example - ```javascript import { mockTracking } from 'helpers/tracking_helper'; // mockTracking(category, documentOverride, spyMethod) -describe('RightSidebar.vue', () => { +describe('CountDropdown.vue', () => { let trackingSpy; let wrapper; + ... + beforeEach(() => { trackingSpy = mockTracking(undefined, wrapper.element, jest.spyOn); }); - const findToggle = () => wrapper.find('[data-testid="toggle"]'); + const findDropdown = () => wrapper.find('[data-testid="dropdown"]'); - it('tracks turning off toggle', () => { - findToggle().trigger('click'); + it('tracks change event', () => { + const dropdown = findDropdown(); + dropdown.element.value = 30; + dropdown.trigger('change'); - expect(trackingSpy).toHaveBeenCalledWith(undefined, 'click_toggle', { - label: 'right_sidebar', - value: 0, + expect(trackingSpy).toHaveBeenCalledWith(undefined, 'change_value', { + value: 30, + label: 'count_dropdown', + extra: { variant: 'counter' }, }); }); }); @@ -241,7 +280,8 @@ describe('RightSidebar.vue', () => { ### Implement raw JavaScript tracking -To call custom event tracking and instrumentation directly from the JavaScript file, call the `Tracking.event` static function. +To track from a vanilla JavaScript file, use the `Tracking.event` static function +(calls [`dispatchSnowplowEvent`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/tracking/dispatch_snowplow_event.js)). The following example demonstrates tracking a click on a button by manually calling `Tracking.event`. @@ -251,7 +291,7 @@ import Tracking from '~/tracking'; const button = document.getElementById('create_from_template_button'); button.addEventListener('click', () => { - Tracking.event('dashboard:projects:index', 'click_button', { + Tracking.event(undefined, 'click_button', { label: 'create_from_template', property: 'template_preview', extra: { |