Allow external links to override type

- for external links such as 'Start now' buttons, we want the specialist link tracker to be able to pick up an alternative value for 'type' from the `data-ga4-link` attribute on the link
- need to modify the existing code as it already checks for `data-ga4-link` on the element and higher, changed to check only the parent and above

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

@@ -46,7 +46,8 @@ window.GOVUK.analyticsGa4.analyticsModules = window.GOVUK.analyticsGa4.analytics
       }
 
       // Code below ensures the tracker plays nicely with the other link tracker
-      var otherLinkTracker = element.closest('[data-ga4-link]')
+      // might have data-ga4-link on the link, so start 'closest' on the parent
+      var otherLinkTracker = element.parentElement.closest('[data-ga4-link]')
       if (otherLinkTracker) {
         var limitToElementClass = otherLinkTracker.getAttribute('data-ga4-limit-to-element-class')
 
@@ -72,7 +73,22 @@ window.GOVUK.analyticsGa4.analyticsModules = window.GOVUK.analyticsGa4.analytics
       if (!href) {
         return
       }
+
       var data = {}
+      var extraAttributes = element.getAttribute('data-ga4-link')
+      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 +101,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'
       }
 

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-link` 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`.
 

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-link', 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++) {