Skip to content

Commit

Permalink
Merge pull request #2283 from alphagov/add-element-tracking-to-track-…
Browse files Browse the repository at this point in the history
…click

Add element tracking to track click
  • Loading branch information
andysellick authored Aug 24, 2021
2 parents 7254544 + 1723d50 commit c35d435
Show file tree
Hide file tree
Showing 5 changed files with 132 additions and 4 deletions.
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@

## Unreleased

* Add element tracking to track click ([PR #2283](https://github.com/alphagov/govuk_publishing_components/pull/2283))
* Fix navigation header layout error that occurs when resizing browser window ([PR #2281](https://github.com/alphagov/govuk_publishing_components/pull/2281))

## 25.5.0
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,14 +10,20 @@ window.GOVUK.Modules = window.GOVUK.Modules || {};
this.$module = $module[0]
this.$module.handleClick = this.handleClick.bind(this)
var trackLinksOnly = this.$module.hasAttribute('data-track-links-only')
var limitToElementClass = this.$module.getAttribute('data-limit-to-element-class')

var that = this
// add a listener to the whole element
this.$module.addEventListener('click', function (e) {
var target = e.target
if (!trackLinksOnly) {
that.$module.handleClick(e.target)
} else if (trackLinksOnly && e.target.tagName === 'A') {
that.$module.handleClick(e.target)
that.$module.handleClick(target)
} else if (trackLinksOnly && target.tagName === 'A') {
if (!limitToElementClass) {
that.$module.handleClick(target)
} else if (limitToElementClass && target.closest('.' + limitToElementClass)) {
that.$module.handleClick(target)
}
}
})
}
Expand Down
2 changes: 1 addition & 1 deletion docs/analytics.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Analytics

The gem now contains the GOV.UK analytics code from `static`, originally from `govuk_frontend_toolkit`. It is not included with the JS from the gem as it is not intended for wider use yet.
The gem now contains the GOV.UK analytics code from `static`, originally from `govuk_frontend_toolkit`.

The following documentation is included from the original for reference only.

Expand Down
89 changes: 89 additions & 0 deletions docs/track-click.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
# Track click script

The gem includes a script that allows tracking to be added to clicked elements with relative ease. It depends upon the main analytics code to function.

Basic use:

```html
<a href="/link"
data-module="gem-track-click"
data-track-category="category"
data-track-action="action"
data-track-label="Foo">
Link
</a>
```

Advanced use. Adds a custom dimension of `dimension29` with a value of `dimension-value`, and a `value` of `9`.

```html
<a href="/link"
data-module="gem-track-click"
data-track-category="category"
data-track-action="action"
data-track-label="label"
data-track-dimension="dimension-value"
data-track-dimension-index="29"
data-track-value="9">
Link
</a>
```

Track with arbitrary JSON:

```html
<a href='/link'
data-module='gem-track-click'
data-track-category='category'
data-track-action='1'
data-track-label='/'
data-track-options='{"dimension28": "foo", "dimension29": "bar"}'>
Link
</a>
```

Specific tracking can also be applied to elements within a container.

```html
<div data-module="gem-track-click">
<a href="/link1"
data-track-category="cat1"
data-track-action="action1"
data-track-label="label1">
Link 1
</a>
<a href="/link2"
data-track-category="cat2"
data-track-action="action2"
data-track-label="label2">
Link 2
</a>
</div>
```

Where specific attributes cannot be applied to elements, links can be tracked with the link href as the tracking label (and other attributes set on the parent). The `data-track-links-only` attribute ensures that only link clicks are tracked (without it, any click inside the element is tracked).

```html
<div data-module="gem-track-click"
data-track-category="category"
data-track-action="action"
data-track-links-only>
<a class="first" href="/link1">Link 1</a>
<a class="second" href="/link2">Link 2</a>
</div>
```

To apply tracking to links within a specific element within part of a page, use the `data-limit-to-element-class` attribute. This is helpful where page content is not editable, e.g. content comes from the content item or a publishing tool.

```html
<div data-module="gem-track-click"
data-track-category="category"
data-track-action="action"
data-track-links-only
data-limit-to-element-class="demoBox">
<a class="first" href="/link1">Link clicks will not be tracked</a>
<div class="demoBox">
<a class="second" href="/link2">Link clicks will be tracked</a>
</div>
</div>
```
Original file line number Diff line number Diff line change
Expand Up @@ -172,6 +172,38 @@ describe('A click tracker', function () {
expect(GOVUK.analytics.trackEvent).toHaveBeenCalledWith('cat2', 'action2', { label: 'label2', transport: 'beacon' })
})

it('tracks only clicks on links within a given element when configured', function () {
element = $(
'<div data-module="gem-track-click" data-track-category="cat1" data-track-action="action1" data-track-links-only data-limit-to-element-class="testBox">' +
'<div class="testBox">' +
'<a class="first" href="#link1">Link 1</a>' +
'<a class="second" href="#link2" ' +
'data-track-category="cat2"' +
'data-track-action="action2"' +
'data-track-label="label2">' +
'Link 2' +
'</a>' +
'</div>' +
'<a class="third" href="#link3">Link 3</a>' +
'<span class="nothing"></span>' +
'</div>'
)

new GOVUK.Modules.GemTrackClick().start(element)

element.find('.nothing')[0].click()
expect(GOVUK.analytics.trackEvent).not.toHaveBeenCalled()

element.find('a.third')[0].click()
expect(GOVUK.analytics.trackEvent).not.toHaveBeenCalled()

element.find('a.first')[0].click()
expect(GOVUK.analytics.trackEvent).toHaveBeenCalledWith('cat1', 'action1', { label: '#link1', transport: 'beacon' })

element.find('a.second')[0].click()
expect(GOVUK.analytics.trackEvent).toHaveBeenCalledWith('cat2', 'action2', { label: 'label2', transport: 'beacon' })
})

it('tracks a click correctly when event target is a child element of trackable element', function () {
element = $(
'<div data-module="gem-track-click">' +
Expand Down

0 comments on commit c35d435

Please sign in to comment.