From b8943690532dcfead6efd40c9faee3f1c936599a Mon Sep 17 00:00:00 2001 From: Andy Sellick Date: Tue, 8 Nov 2022 11:56:23 +0000 Subject: [PATCH] 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 --- .../_layout_super_navigation_header.html.erb | 4 +- .../feedback/_yes_no_banner.html.erb | 6 +- docs/analytics-ga4/analytics.md | 10 +++ docs/analytics-ga4/ga4-event-tracker.md | 20 ++--- docs/analytics-ga4/ga4-link-tracker.md | 75 +++++++++++++++++++ docs/analytics/track-click.md | 8 +- spec/javascripts/components/feedback-spec.js | 4 +- 7 files changed, 106 insertions(+), 21 deletions(-) create mode 100644 docs/analytics-ga4/ga4-link-tracker.md 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 index 7d3f99fcc4..31ceec3ff0 100644 --- 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 index a984998d02..eee5e6c1c2 100644 --- 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 %>
  • -
  • -
    • @@ -39,7 +39,7 @@ diff --git a/docs/analytics-ga4/analytics.md b/docs/analytics-ga4/analytics.md index b74952568f..5abd1db201 100644 --- 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 index 35d1f1a1cb..5cc6be2668 100644 --- 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
    -
    +
    +
    ``` 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 new file mode 100644 index 0000000000..1c51c6bff9 --- /dev/null +++ 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 + + Link + +``` + +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 +
    + + Link 1 + + + Link 2 + +
    +``` + +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 +
    + This link will be tracked + + This link will also be tracked even though it contains child elements + + This span will not be tracked +
    +``` + +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 +
    + This link will not be tracked +
    + This link will be tracked +
    +
    +``` diff --git a/docs/analytics/track-click.md b/docs/analytics/track-click.md index 4ccf979a5b..7a828c7fc2 100644 --- 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> - This link will be tracked - + This link will be tracked + This link will also be tracked even though it contains child elements This span will not be tracked @@ -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"> - This link will not be tracked + This link will not be tracked
    - This link will be tracked + This link will be tracked
    ``` diff --git a/spec/javascripts/components/feedback-spec.js b/spec/javascripts/components/feedback-spec.js index 2077664c47..37a984c148 100644 --- a/spec/javascripts/components/feedback-spec.js +++ b/spec/javascripts/components/feedback-spec.js @@ -17,12 +17,12 @@ describe('Feedback component', function () { '' + '' + '
  • ' + - '' + '
    • ' + '
  • ' + - '' + '
    • ' +