Add step by step nav GA4 tracking

CHANGELOG.md

@@ -13,6 +13,7 @@
 * Add the keyboard shim for link buttons ([PR #3027](https://github.com/alphagov/govuk_publishing_components/pull/3027))
 * Remove unused axe-core option from options parameter ([PR #3094](https://github.com/alphagov/govuk_publishing_components/pull/3094))
 * Minor ecommerce tracking refactor ([PR #3098](https://github.com/alphagov/govuk_publishing_components/pull/3098))
+* Add step by step nav GA4 tracking ([PR #3052](https://github.com/alphagov/govuk_publishing_components/pull/3052))
 
 ## 33.0.0
 
@@ -25,7 +26,6 @@
 * Simplify the way ga4 tracking is added to accordions ([PR #3082](https://github.com/alphagov/govuk_publishing_components/pull/3082))
 * Rename section and themes property names ([PR #3092](https://github.com/alphagov/govuk_publishing_components/pull/3092))
 
-
 ## 32.1.0
 
 * Calculate viewport width correctly for navbar in Chrome and Firefox when Mac scrollbars are enabled ([PR #3016](https://github.com/alphagov/govuk_publishing_components/pull/3016))

app/assets/javascripts/govuk_publishing_components/components/step-by-step-nav.js

@@ -36,6 +36,9 @@ window.GOVUK.Modules = window.GOVUK.Modules || {};
 
     this.$module.uniqueId = this.$module.getAttribute('data-id') || false
 
+    this.$module.dataModule = this.$module.getAttribute('data-module')
+    this.$module.isGa4Enabled = this.$module.dataModule ? this.$module.dataModule.indexOf('ga4-event-tracker') !== -1 : false
+
     if (this.$module.uniqueId) {
       this.$module.sessionStoreLink = this.$module.sessionStoreLink + '_' + this.$module.uniqueId
     }
@@ -78,6 +81,12 @@ window.GOVUK.Modules = window.GOVUK.Modules || {};
 
     this.$module.insertBefore(showAll, steps)
     this.$module.showOrHideAllButton = this.$module.querySelectorAll('.js-step-controls-button')[0]
+
+    // if GA4 is enabled, set attributes on 'show all sections' for tracking using ga4-event-tracker
+    if (this.$module.isGa4Enabled) {
+      var showAllAttributesGa4 = { event_name: 'select_content', type: 'step by step', index: 0, index_total: this.$module.totalSteps }
+      this.$module.showOrHideAllButton.setAttribute('data-ga4-event', JSON.stringify(showAllAttributesGa4))
+    }
   }
 
   Gemstepnav.prototype.addShowHideToggle = function () {
@@ -169,12 +178,24 @@ window.GOVUK.Modules = window.GOVUK.Modules || {};
       var title = thisel.querySelectorAll('.js-step-title')[0]
       var contentId = thisel.querySelectorAll('.js-panel')[0].getAttribute('id')
       var titleText = title.textContent || title.innerText // IE8 fallback
+      var ga4Data = ''
+
+      if (this.$module.isGa4Enabled) {
+        var ga4JSON = {
+          event_name: 'select_content',
+          type: 'step by step',
+          text: titleText.trim(),
+          index: i + 1,
+          index_total: this.$module.totalSteps
+        }
+        ga4Data = "data-ga4-event='" + JSON.stringify(ga4JSON) + "'" // Construct GA4 data-attributes for ga4-event-tracker.
+      }
 
       title.outerHTML =
         '<span class="js-step-title">' +
           '<button ' +
             'class="gem-c-step-nav__button gem-c-step-nav__button--title js-step-title-button" ' +
-            'aria-expanded="false" aria-controls="' + contentId + '">' +
+            'aria-expanded="false" aria-controls="' + contentId + '" ' + ga4Data + '>' +
               '<span class="gem-c-step-nav____title-text-focus">' +
                   '<span class="gem-c-step-nav__title-text js-step-title-text">' + titleText + '</span>' +
                   '<span class="govuk-visually-hidden gem-c-step-nav__section-heading-divider">, </span>' +

app/views/govuk_publishing_components/components/_step_by_step_nav.html.erb

@@ -15,10 +15,13 @@
   step_number = 0
 
   step_nav_helper = GovukPublishingComponents::Presenters::StepByStepNavHelper.new
+
+  ga4_tracking ||= false
 %>
 <% if steps %>
   <div
-    data-module="gemstepnav"
+    data-module="gemstepnav<% if ga4_tracking %> ga4-event-tracker<% end %>"
+    <%= "data-ga4-expandable" if ga4_tracking %>
     class="gem-c-step-nav js-hidden <% if small %>govuk-!-display-none-print<% end %> <% unless small %>gem-c-step-nav--large<% end %>"
     <%= "data-remember" if remember_last_step %>
     <%= "data-id=#{tracking_id}" if tracking_id %>

app/views/govuk_publishing_components/components/docs/step_by_step_nav.yml

@@ -72,6 +72,40 @@ examples:
           ]
         }
       ]
+  with_google_analytics_4_tracking:
+    description: |
+      The ga4_tracking boolean allows you to add Google Analytics 4 (GA4) tracking to your component.
+      Setting this to true will add the `ga4-event-tracker` module to your component. The JavaScript will then add a `data-ga4-event` attribute and `data-ga4-expandable` attribute to the "Show all steps" button, and each clickable Step heading.
+      GA4 will then track these elements when they are expanded or collapsed.
+      `data-ga4-event` contains a JSON with event data relevant to our tracking. `data-ga4-expandable` enables the value of `aria-expanded` to be captured.
+      See the [ga4-event-tracker](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/analytics-ga4/ga4-event-tracker.md) docs for more information.
+    data:
+      ga4_tracking: true
+      steps: [
+        {
+          title: "Do something",
+          contents: [
+            {
+              type: 'paragraph',
+              text: 'This is a paragraph of text.'
+            },
+            {
+              type: 'paragraph',
+              text: 'This is also a paragraph of text that intentionally contains lots of words in order to fill the width of the page successfully to check layout and so forth.'
+            }
+          ],
+        },
+        {
+          title: "Do something thing else",
+          logic: "and",
+          contents: [
+            {
+              type: 'paragraph',
+              text: 'Some more text.'
+            },
+          ]
+        },
+      ]
   with_unique_tracking:
     description: |
       In order to identify the step by step navigation the component is part of, we need to track a unique ID of the navigation in Google Analytics. This ID should be the same across all pages that are linked from and are part of that navigation. Its value is included in any tracking events, specifically in dimension96. It refers to the ID of the step nav page.

spec/components/step_by_step_nav_spec.rb

@@ -253,4 +253,11 @@ def stepnav
 
     assert_select ".gem-c-step-nav[data-id='harold']"
   end
+
+  it "adds ga4 attributes" do
+    render_component(steps: stepnav, ga4_tracking: true)
+
+    assert_select ".gem-c-step-nav[data-ga4-expandable]"
+    assert_select ".gem-c-step-nav[data-module='gemstepnav ga4-event-tracker']"
+  end
 end

spec/javascripts/components/step-by-step-nav-spec.js

@@ -4,7 +4,7 @@
 describe('A stepnav module', function () {
   'use strict'
 
-  var $element
+  var $element, element
   var html =
     '<div data-module="gemstepnav" class="gem-c-step-nav js-hidden" data-id="unique-id" data-show-text="Show" data-hide-text="Hide" data-show-all-text="Show all steps" data-hide-all-text="Hide all steps">' +
       '<ol class="gem-c-step-nav__steps">' +
@@ -921,4 +921,28 @@ describe('A stepnav module', function () {
       })
     })
   })
+
+  describe('with GA4 tracking enabled', function () {
+    beforeEach(function () {
+      element = document.createElement('div')
+      element.innerHTML = html
+      element.childNodes[0].setAttribute('data-module', 'gemstepnav ga4-event-tracker')
+      element.childNodes[0].setAttribute('data-ga4-expandable', '')
+      new GOVUK.Modules.Gemstepnav(element.childNodes[0]).init()
+    })
+
+    it('adds the "Show all" JSON to the JS generated "show all steps" button', function () {
+      var stepNav = element.childNodes[0]
+      var showAllButton = stepNav.querySelector('button.js-step-controls-button')
+
+      expect(showAllButton.getAttribute('data-ga4-event')).toEqual('{"event_name":"select_content","type":"step by step","index":0,"index_total":3}')
+    })
+
+    it('adds the data-ga4-event attribute to the JS generated step button', function () {
+      var stepNav = element.childNodes[0]
+      var stepButton = stepNav.querySelector('#topic-step-one .js-step-title button')
+
+      expect(stepButton.getAttribute('data-ga4-event')).toEqual('{"event_name":"select_content","type":"step by step","text":"Topic Step One","index":1,"index_total":3}')
+    })
+  })
 })