Merge pull request #3935 from alphagov/ga4-button

Track 'Start now' buttons with a specific GA4 type

CHANGELOG.md

@@ -9,6 +9,7 @@
 
 ## Unreleased
 
+* Track 'Start now' buttons with a specific GA4 type ([PR #3935](https://github.com/alphagov/govuk_publishing_components/pull/3935))
 * Use component wrapper in document list component ([PR #3933](https://github.com/alphagov/govuk_publishing_components/pull/3933))
 
 ## 37.9.0

app/assets/javascripts/govuk_publishing_components/analytics-ga4/ga4-specialist-link-tracker.js

@@ -72,7 +72,22 @@ window.GOVUK.analyticsGa4.analyticsModules = window.GOVUK.analyticsGa4.analytics
       if (!href) {
         return
       }
+
       var data = {}
+      var extraAttributes = element.getAttribute('data-ga4-attributes')
+      if (extraAttributes) {
+        try {
+          extraAttributes = JSON.parse(extraAttributes)
+          // make sure the data object remains an object - JSON.parse can return a string
+          for (var attrname in extraAttributes) {
+            data[attrname] = extraAttributes[attrname]
+          }
+        } catch (e) {
+          // fall back to the empty data object if something goes wrong
+          console.error('GA4 configuration error: ' + e.message, window.location)
+        }
+      }
+
       var mailToLink = false
       if (window.GOVUK.analyticsGa4.core.trackFunctions.isMailToLink(href)) {
         data.event_name = 'navigation'
@@ -85,7 +100,7 @@ window.GOVUK.analyticsGa4.analyticsModules = window.GOVUK.analyticsGa4.analytics
         data.external = window.GOVUK.analyticsGa4.core.trackFunctions.isExternalLink(href) ? 'true' : 'false'
       } else if (window.GOVUK.analyticsGa4.core.trackFunctions.isExternalLink(href)) {
         data.event_name = 'navigation'
-        data.type = 'generic link'
+        data.type = data.type || 'generic link'
         data.external = 'true'
       }
 

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

@@ -1,5 +1,6 @@
 <%
   add_gem_component_stylesheet("button")
+  disable_ga4 ||= false
 
   # button_helper.css_classes generates "gem-c-button"
   shared_helper = GovukPublishingComponents::Presenters::SharedHelper.new(local_assigns)

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

@@ -44,6 +44,14 @@ examples:
       href: '#'
       start: true
       rel: external
+  start_now_button_without_ga4_attributes:
+    description: By default the start now button version of this component includes a `data-ga4-attributes` attribute that is used by the specialist (external) link tracker to uniquely identify start now buttons. This attribute can be removed using the `disable_ga4` option.
+    data:
+      text: Start now
+      disable_ga4: true
+      href: '#'
+      start: true
+      rel: external
   secondary_button:
     data:
       text: Secondary button

docs/analytics-ga4/ga4-specialist-link-tracker.md

@@ -72,7 +72,7 @@ In the example above, on a left click of the link, the following would be pushed
 
 Preview links would turn `type` to `preview`.
 
-External links would turn `event_name` to `navigation` and `type` to `generic link`.
+External links would turn `event_name` to `navigation` and `type` to `generic link`. `type` can be overridden by putting a `data-ga4-attributes` attribute on a link, containing a JSON snippet with an alternative `type`. This is done on 'Start now' buttons to uniquely identify them.
 
 Mailto links would turn turn `event_name` to `navigation` and `type` to `email`.
 

lib/govuk_publishing_components/presenters/button_helper.rb

@@ -28,6 +28,7 @@ class ButtonHelper
                   :aria_describedby
 
       def initialize(local_assigns)
+        @disable_ga4 = local_assigns[:disable_ga4]
         @href = local_assigns[:href]
         @text = local_assigns[:text]
         @title = local_assigns[:title]
@@ -45,6 +46,7 @@ def initialize(local_assigns)
         @target = local_assigns[:target]
         @type = local_assigns[:type]
         @start = local_assigns[:start]
+        @data_attributes[:ga4_attributes] = ga4_attribute if start
         @secondary = local_assigns[:secondary]
         @secondary_quiet = local_assigns[:secondary_quiet]
         @secondary_solid = local_assigns[:secondary_solid]
@@ -129,6 +131,10 @@ def get_margin_bottom(margin, info_text)
 
         [*0..9].include?(margin) ? "govuk-!-margin-bottom-#{margin}" : legacy_class
       end
+
+      def ga4_attribute
+        { type: "start button" }.to_json unless @disable_ga4
+      end
     end
   end
 end

spec/components/button_spec.rb

@@ -15,6 +15,7 @@ def component_name
     assert_select ".govuk-button[type=submit]", text: "Submit"
     assert_select ".govuk-button--start", false
     assert_select ".gem-c-button__info-text", false
+    assert_select "[data-ga4-attributes]", false
   end
 
   it "renders text correctly" do
@@ -46,6 +47,14 @@ def component_name
     render_component(text: "Start now", href: "#", start: true)
     assert_select ".govuk-button[href='#'] span", text: /Start now/
     assert_select ".govuk-button--start"
+    assert_select ".govuk-button--start[data-ga4-attributes='{\"type\":\"start button\"}']"
+  end
+
+  it "renders start now button with GA4 attributes disabled" do
+    render_component(text: "Start now", href: "#", start: true, disable_ga4: true)
+    assert_select ".govuk-button[href='#'] span", text: /Start now/
+    assert_select ".govuk-button--start"
+    assert_select ".govuk-button--start[data-ga4-attributes='{\"type\":\"start button\"}']", false
   end
 
   it "renders secondary button" do

spec/javascripts/govuk_publishing_components/analytics-ga4/ga4-specialist-link-tracker.spec.js

@@ -49,6 +49,10 @@ describe('A specialist link tracker', function () {
               '<a href="https://www.nationalarchives.gov.uk/2" link_domain="https://www.nationalarchives.gov.uk" path="/2"></a>' +
               '<a href="https://www.nationalarchives.gov.uk/3.pdf" link_domain="https://www.nationalarchives.gov.uk" path="/3.pdf">National Archives PDF</a>' +
             '</div>' +
+            '<div class="external-links-with-data-attributes">' +
+              '<a href="http://www.nationalarchives.gov.uk/1" link_domain="http://www.nationalarchives.gov.uk" path="/1"> National Archives </a>' +
+              '<a href="http://www.nationalarchives.gov.uk/2" link_domain="http://www.nationalarchives.gov.uk" path="/2"> National Archives </a>' +
+            '</div>' +
             '<div class="www-less-external-links">' +
               '<a href="http://nationalarchives.gov.uk/1" path="/1" link_domain="http://nationalarchives.gov.uk"> National Archives </a>' +
               '<a href="https://nationalarchives.gov.uk/2" path="/2" link_domain="https://nationalarchives.gov.uk"></a>' +
@@ -108,6 +112,33 @@ describe('A specialist link tracker', function () {
       }
     })
 
+    it('reads type from data-ga4-link attributes on external links', function () {
+      var linksToTest = document.querySelectorAll('.external-links-with-data-attributes a')
+      var attributes = [
+        {
+          type: 'specific type'
+        },
+        'invalid JSON'
+      ]
+      var types = [
+        'specific type',
+        'generic link'
+      ]
+
+      for (var i = 0; i < linksToTest.length; i++) {
+        var link = linksToTest[i]
+        link.setAttribute('data-ga4-attributes', JSON.stringify(attributes[i]))
+        window.dataLayer = []
+        GOVUK.triggerEvent(link, 'click')
+        expected.event_data.link_domain = link.getAttribute('link_domain')
+        expected.event_data.url = link.getAttribute('href')
+        expected.event_data.text = link.innerText.trim()
+        expected.event_data.type = types[i]
+
+        expect(window.dataLayer[0]).toEqual(expected)
+      }
+    })
+
     it('detects external click events on www. missing external links', function () {
       var linksToTest = document.querySelectorAll('.www-less-external-links a')
       for (var i = 0; i < linksToTest.length; i++) {