Update references and documentation

- update documentation to reflect new changes - update other bits of code that rely on the event tracker, where data-ga4 attributes must now be data-ga4-event - removing entirely from feedback-spec.js as not needed for the tests to run
alphagov · Nov 24, 2022 · b894369 · b894369
1 parent a6c710e
commit b894369
Show file tree

Hide file tree

Showing 7 changed files with 106 additions and 21 deletions.
diff --git a/app/views/govuk_publishing_components/components/_layout_super_navigation_header.html.erb b/app/views/govuk_publishing_components/components/_layout_super_navigation_header.html.erb
@@ -78,7 +78,7 @@
         hidden
         id="super-navigation-menu-toggle"
         type="button"
-        data-ga4="<%= {
+        data-ga4-event="<%= {
           "event_name": "select_content",
           "type": "header menu bar",
           "text": "Menu",
@@ -233,7 +233,7 @@
         hidden
         id="super-search-menu-toggle"
         type="button"
-        data-ga4="<%= {
+        data-ga4-event="<%= {
           "event_name": "select_content",
           "type": "header menu bar",
           "text": "Search",

diff --git a/app/views/govuk_publishing_components/components/feedback/_yes_no_banner.html.erb b/app/views/govuk_publishing_components/components/feedback/_yes_no_banner.html.erb
@@ -21,12 +21,12 @@
             <% end %>
           </li>
           <li class="gem-c-feedback__option-list-item">
-            <button class="govuk-button gem-c-feedback__prompt-link js-page-is-useful" data-track-category="yesNoFeedbackForm" data-track-action="ffYesClick" data-ga4='{"event_name":"form_submit","type":"feedback","text":"Yes", "section": "Is this page useful?"}'>
+            <button class="govuk-button gem-c-feedback__prompt-link js-page-is-useful" data-track-category="yesNoFeedbackForm" data-track-action="ffYesClick" data-ga4-event='{"event_name":"form_submit","type":"feedback","text":"Yes", "section": "Is this page useful?"}'>
               <%= t("components.feedback.yes") %> <span class="govuk-visually-hidden"><%= t("components.feedback.is_useful") %></span>
             </button>
           </li>
           <li class="gem-c-feedback__option-list-item">
-            <button class="govuk-button gem-c-feedback__prompt-link js-toggle-form js-page-is-not-useful" data-track-category="yesNoFeedbackForm" data-track-action="ffNoClick" aria-controls="page-is-not-useful" aria-expanded="false" data-ga4='{"event_name":"form_submit","type":"feedback","text":"No", "section": "Is this page useful?"}'>
+            <button class="govuk-button gem-c-feedback__prompt-link js-toggle-form js-page-is-not-useful" data-track-category="yesNoFeedbackForm" data-track-action="ffNoClick" aria-controls="page-is-not-useful" aria-expanded="false" data-ga4-event='{"event_name":"form_submit","type":"feedback","text":"No", "section": "Is this page useful?"}'>
               <%= t("components.feedback.no") %> <span class="govuk-visually-hidden"><%= t("components.feedback.is_not_useful") %></span>
             </button>
           </li>
@@ -39,7 +39,7 @@
     </div>
 
     <div class="gem-c-feedback__prompt-questions gem-c-feedback__prompt-questions--something-is-wrong js-prompt-questions" hidden>
-      <button class="govuk-button gem-c-feedback__prompt-link js-toggle-form js-something-is-wrong" data-track-category="Onsite Feedback" data-track-action="GOV-UK Open Form" aria-controls="something-is-wrong" aria-expanded="false" data-ga4='{"event_name":"form_submit","type":"feedback","text":"Report a problem with this page", "section": "Is this page useful?"}'>
+      <button class="govuk-button gem-c-feedback__prompt-link js-toggle-form js-something-is-wrong" data-track-category="Onsite Feedback" data-track-action="GOV-UK Open Form" aria-controls="something-is-wrong" aria-expanded="false" data-ga4-event='{"event_name":"form_submit","type":"feedback","text":"Report a problem with this page", "section": "Is this page useful?"}'>
         <%= t("components.feedback.something_wrong") %>
       </button>
     </div>

diff --git a/docs/analytics-ga4/analytics.md b/docs/analytics-ga4/analytics.md
@@ -54,6 +54,16 @@ When cookie consent is given, `init-ga4.js` looks through the `analyticsModules`
 
 Where analytics code is required as a [GOV.UK JavaScript Module](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/javascript-modules.md), the code structure for the [existing model for deferred loading](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/javascript-modules.md#modules-and-cookie-consent) should be used.
 
+## Link and event tracking
+
+There are several types of user initiated tracking. To distinguish them and simplify the code, we consider them as the following:
+
+- interactions with [links](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/analytics-ga4/ga4-link-tracker.md) where tracking is added using data attributes on specific links
+- interactions with [specialist links](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/analytics-ga4/ga4-specialist-link-tracker.md), e.g. external links, download links, mailto links, where tracking is determined automatically by the content of the link
+- interactions with [buttons or other interactive elements](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/analytics-ga4/ga4-event-tracker.md) e.g. details elements, where tracking is added using data attributes on specific elements
+
+Each type of tracking is handled by a separate script, but some code is shared between them as they do similar things.
+
 ## Data schemas
 
 All of the data sent to GTM is based on a common schema.

diff --git a/docs/analytics-ga4/ga4-event-tracker.md b/docs/analytics-ga4/ga4-event-tracker.md
@@ -1,23 +1,23 @@
-# Google Analytics event tracker
+# Google Analytics 4 event tracker
 
-This is a script to allow event tracking (e.g. clicks) through Google Tag Manager to be added to any element using data attributes.
+This script is intended for adding GA4 tracking to interactive elements such as buttons or details elements. It depends upon the main GA4 analytics code to function.
 
 ## Basic use
 
 ```html
 <div data-module="ga4-event-tracker">
-  <div data-ga4='{"event_name":"select_content", "type":"something", "index":0, "index_total":1, "text":"Click me"}'>
+  <button data-ga4-event='{ "event_name": "select_content", "type": "something", "index": "0", "index_total": "1", "text": "Click me"}'>
     Click me
-  </div>
+  </button>
 </div>
 ```
 
 The module is initialised on the parent element, but tracking only occurs when clicks happen:
 
-- on child elements that have a valid `data-ga4` attribute
-- on the parent if it has a valid `data-ga4` attribute
+- on child elements that have a valid `data-ga4-event` attribute
+- on the parent if it has a valid `data-ga4-event` attribute
 
-A valid `data-ga4` attribute is a JSON string that can be parsed into an object, that contains a recognised value for `event_name`. Pushes to the dataLayer that do not include a valid `event_name` attribute will be ignored by Tag Manager.
+A valid `data-ga4-event` attribute is a JSON string that can be parsed into an object, that contains a recognised value for `event_name` (this is added automatically by the event tracker). Pushes to the dataLayer that do not include a valid `event_name` attribute will be ignored by Tag Manager.
 
 In the example above, the following would be pushed to the dataLayer. Note that the schema automatically populates empty values, and that attributes not in the schema are ignored.
 
@@ -40,7 +40,7 @@ In the example above, the following would be pushed to the dataLayer. Note that
 
 ## Advanced use
 
-In some scenarios we use components that cannot be modified directly (i.e. unable to place the `data-ga4` attribute on the element as shown in the 'Basic use' section). In these cases, we attach the necessary data attributes for tracking by passing an argument containing our data attributes to the render method.
+In some scenarios we use components that cannot be modified directly (i.e. unable to place the `data-ga4-event` attribute on the element as shown in the 'Basic use' section). In these cases, we attach the necessary data attributes for tracking by passing an argument containing our data attributes to the render method.
 
 Many components already accept data attributes in this way (see the [component guide](https://components.publishing.service.gov.uk/component-guide) for examples) but some, like the accordion, are more complicated.
 
@@ -78,9 +78,9 @@ It is also complicated by the fact that the JavaScript that creates this element
 - the 'Show/hide all' link is created by govuk-frontend JavaScript
 - the accordion JavaScript reads `data-show-all-attributes`
   - it creates a `data-` attribute on the 'Show/hide all' link for each key in the JSON
-  - in the example above, the result will be `data-ga4="{ "event_name": "select_content", "type": "accordion" }"`
+  - in the example above, the result will be `data-ga4-event="{ "event_name": "select_content", "type": "accordion" }"`
 - wrap the accordion in the event tracking script
-  - tracking will be activated by clicks on elements with a `data-ga4` attribute
+  - tracking will be activated by clicks on elements with a `data-ga4-event` attribute
   - it checks for an `aria-expanded` attribute if the clicked element or parent element contains a `data-ga4-expandable` value or the `gem-c-accordion` class. If it detects one of those, it sets the `action` of the GA data accordingly.
   - the current text of the clicked element is also recorded (this can be overridden to a non-dynamic value by including `text` in the attributes if required)
 

diff --git a/docs/analytics-ga4/ga4-link-tracker.md b/docs/analytics-ga4/ga4-link-tracker.md
@@ -0,0 +1,75 @@
+# Google Analytics 4 link tracker
+
+This script is intended for adding GA4 tracking to links. It depends upon the main GA4 analytics code to function.
+
+## Basic use (single link)
+
+```html
+<a
+  href="/link"
+  data-module="ga4-link-tracker"
+  data-ga4-link='{ "event_name": "navigation", "type": "home page", "index": 0, "index_total": 1, "section": "name of section" }'>
+    Link
+</a>
+```
+
+Note that the specific detail of the `data-ga4-link` attribute will depend on the context of the link.
+
+## Basic use (multiple links)
+
+Specific tracking can be applied to multiple elements within a container, by applying the data module once to the parent element.
+
+```html
+<div data-module="ga4-link-tracker">
+  <a
+    href="/a-page"
+    data-ga4-link='{ "event_name": "navigation", "type": "browse", "index": "0", "index_total": "2", "section": "name of section" }'>
+    Link 1
+  </a>
+  <a
+    href="/another-page"
+    data-ga4-link='{ "event_name": "navigation", "type": "browse", "index": "1", "index_total": "2", "section": "name of section" }'>
+    Link 2
+  </a>
+</div>
+```
+
+Note that the specific detail of the `data-ga4-link` attribute will depend on the context of the link.
+
+## Track links within content
+
+Where tracking attributes cannot be directly applied to elements, links can be tracked with details applied to the parent. In this configuration the link text and href are automatically determined and included in the event data. This is helpful where page content is not editable, e.g. content comes from the content item or a publishing tool.
+
+The `data-ga4-track-links-only` attribute ensures that only link clicks are tracked (without it, any click inside the element is tracked).
+
+```html
+<div
+  data-module="ga4-link-tracker"
+  data-ga4-link='{ "event_name": "navigation", "type": "browse", "section": "name of section" }'
+  data-ga4-track-links-only>
+  <a href="/link1">This link will be tracked</a>
+  <a href="/link2">
+    <span>This link will also be tracked even though it contains child elements</span>
+  </a>
+  <span>This span will not be tracked</span>
+</div>
+```
+
+Note that in this configuration specific values such as `index` and `index_total` cannot currently be applied to links.
+
+## Track links within content within a specific element
+
+To apply tracking to links within a specific element within part of a page, use the `data-ga4-limit-to-element-class` alongside the `data-ga4-track-links-only` 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="ga4-link-tracker"
+  data-ga4-link='{ "event_name": "navigation", "type": "browse", "section": "name of section" }'
+  data-ga4-track-links-only
+  data-ga4-limit-to-element-class="demoBox">
+  <a href="/link1">This link will not be tracked</a>
+  <div class="demoBox">
+    <a href="/link2">This link will be tracked</a>
+  </div>
+</div>
+```
diff --git a/docs/analytics/track-click.md b/docs/analytics/track-click.md
@@ -79,8 +79,8 @@ Where tracking attributes cannot be applied to elements, links can be tracked wi
   data-track-category="category"
   data-track-action="action"
   data-track-links-only>
-  <a class="first" href="/link1">This link will be tracked</a>
-  <a class="second" href="/link2">
+  <a href="/link1">This link will be tracked</a>
+  <a href="/link2">
     <span>This link will also be tracked even though it contains child elements</span>
   </a>
   <span>This span will not be tracked</span>
@@ -97,9 +97,9 @@ To apply tracking to links within a specific element within part of a page, use
   data-track-action="action"
   data-track-links-only
   data-limit-to-element-class="demoBox">
-  <a class="first" href="/link1">This link will not be tracked</a>
+  <a href="/link1">This link will not be tracked</a>
   <div class="demoBox">
-    <a class="second" href="/link2">This link will be tracked</a>
+    <a href="/link2">This link will be tracked</a>
   </div>
 </div>
 ```
diff --git a/spec/javascripts/components/feedback-spec.js b/spec/javascripts/components/feedback-spec.js
@@ -17,12 +17,12 @@ describe('Feedback component', function () {
                 '</a>' +
               '</li>' +
               '<li class="gem-c-feedback__option-list-item">' +
-                '<button class="govuk-button gem-c-feedback__prompt-link js-page-is-useful" data-track-category="yesNoFeedbackForm" data-track-action="ffYesClick" data-ga4="{"event_name":"form_submit","type":"feedback","text":"Yes", "section": "Is this page useful?"}">' +
+                '<button class="govuk-button gem-c-feedback__prompt-link js-page-is-useful" data-track-category="yesNoFeedbackForm" data-track-action="ffYesClick">' +
                   'Yes <span class="govuk-visually-hidden">this page is useful</span>' +
                 '</button>' +
               '</li>' +
               '<li class="gem-c-feedback__option-list-item">' +
-                '<button class="govuk-button gem-c-feedback__prompt-link js-toggle-form js-page-is-not-useful" data-track-category="yesNoFeedbackForm" data-track-action="ffNoClick" aria-controls="page-is-not-useful" aria-expanded="false" data-ga4="{"event_name":"form_submit","type":"feedback","text":"No", "section": "Is this page useful?"}">' +
+                '<button class="govuk-button gem-c-feedback__prompt-link js-toggle-form js-page-is-not-useful" data-track-category="yesNoFeedbackForm" data-track-action="ffNoClick" aria-controls="page-is-not-useful" aria-expanded="false">' +
                   'No <span class="govuk-visually-hidden">this page is not useful</span>' +
                 '</button>' +
               '</li>' +