@govuk-one-login/one-login-analytics

GOV UK One Login GA4 Implementation

This package enables GOV UK LOGIN frontend Node.js applications to use Google Tag Manager and Google Analytics 4.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
2. Getting Started
   • Installation

About The Project

The GDS One Login GA4 (Google Analytics 4) node package is a shared, reusable solution created to facilitate the upgrade from GAU to GA4 across the One Login programme as GAU is being retired mid 2024.

The purpose of this package is to make it as easy as possible for the various pods that make up the One Login journey to upgrade their analytics while having as minimal an impact as possible on the dev teams time and effort.

The package is owned by the DI Frontend Capability team, part of the development of this tool involves ongoing discovery with the pods responsible for maintaining the frontend repositories that make up the One Login journey. As more information is collated, the package and documentation will be updated. As such, it is considered a WIP and the pods will be notified when a stable release is ready.

(back to top)

Getting Started

Installation

1. Install NPM package

   npm install @govuk-one-login/one-login-analytics

2. Configure your node application's startup file (example: app.js or index.js) and add a new virtual directory:

   app.use(
     "/ga4-assets",
     express.static(
       path.join(
         __dirname,
         "../node_modules/@govuk-one-login/one-login-analytics/lib",
       ),
     ),
   );

   [!WARNING] Check if the path to your node module folder is the correct one. [!WARNING]

3. Set a variable “ga4ContainerId” with the value of your google tag manager id (format: GTM-XXXXXXX) and be sure it’s accessible to your base nunjucks template (example: src/views/common/layout/base.njk). You can also set the variable uaContainerId with the value of your google tag container id (format: GTM-XXXXXXX).

[!NOTE] Different methods exist if you want to set this variable. Some projects use a middleware, some will prefer to use another method. [!NOTE]

4. Add this block of code into your base nunjucks template:

    <script src="/ga4-assets/analytics.js"></script>
    <script>
    window.DI.appInit({ga4ContainerId: "{{ga4ContainerId}}", uaContainerId: '{{ uaContainerId }}'})
    </script>

   window.DI.appInit can take another parameter: an object of settings. That can be used if you want to disable some options. This is the property of this settings object:

   • disableGa4Tracking (boolean): disable GA4 trackers
   • disableUaTracking (boolean): disable Universal Analytics tracker
   • cookieDomain (string): specify the domain the analytics consent cookie should be raised against (default is "account.gov.uk")

Example of call:

window.DI.appInit(
  {
    ga4ContainerId: "{{ga4ContainerId}}",
    uaContainerId: "{{ uaContainerId }}",
  },
  {
    disableGa4Tracking: true,
    disableUaTracking: true,
    cookieDomain: "{{ cookieDomain }}",
  },
);

[!NOTE] window.DI.appInit is a function loaded from analytics.js. That will create a new instance of our analytics library and store into window.DI.analyticsGa4 [!NOTE]

Analytics Cookie Consent

The Cookie class is responsible for managing cookies consent about analytics. It provides methods and fields to handle cookie-related operations:

• Set the cookie when the visitor decides to accept or reject any analytics tracking
• Hide the cookie banner that displays a message when the visitor has decided if he rejects or accepts the analytics tracking
• Show the element that displays a message when consent is not given
• Show the element that displays a message when consent is given
• Hide the cookie banner when the visitor wants to hide the accepted or rejected message

[!NOTE] Tips: 1/ You can get analytics cookie consent status (true or false) by calling the function hasConsentForAnalytics:

window.DI.analyticsGa4.cookie.hasConsentForAnalytics();

2/ You can revoke analytics cookie consent by calling the function setBannerCookieConsent:

window.DI.analyticsGa4.cookie.setBannerCookieConsent(
  false,
  youranalyticsdomain,
);

[!NOTE]

Page View Tracker

Page view tracking allows us to see which pages are most visited, where your visitors are coming from, etc. It can be called by using the method trackOnPageLoad of the object pageViewTracker stored into the analytics library (analyticsGa4)

It takes as a unique parameter an object define by :

• statusCode (number): Status code of the page.
• englishPageTitle (string): English version of the page title.
• taxonomy_level1 (string): Taxonomies are hierarchical tool that allows us to filter data for reporting and insights purposes.
• taxonomy_level2 (string): Taxonomies are hierarchical tool that allows us to filter data for reporting and insights purposes.
• content_id (string): Content ID is a unique ID for each front end display on a given page.
• logged_in_status (boolean): Whether a user is logged in or logged out.
• dynamic (boolean): This parameter indicates whether the page has multiple versions and uses the same URL.

Example:

window.DI.analyticsGa4.pageViewTracker.trackOnPageLoad({
  statusCode: 200,
  englishPageTitle: "english version of the page title",
  taxonomy_level1: "test tax1",
  taxonomy_level2: "test tax2",
  content_id: "<e4a3603d-2d3c-4ff1-9b80-d72c1e6b7a58>",
  logged_in_status: true,
  dynamic: true,
});

Navigation Tracker

Navigation tracking allows us to see exactly how often each navigation link is used. It's triggered by a listener on the click event.

We are tracking different types of link:

• Generic Inbound Links: When a user clicks on a link and it is an inbound link which is defined as any links that point to a domain that does match the domain of the current page
• Generic Inbound Button: When a user clicks on a button and it is an inbound link which is defined as any links that point to a domain that does match the domain of the current page
• Generic Outbound Links: When a user clicks on a link and it is an outbound link, which is defined as any links that point to a domain that does not match the domain of the current page.
• Header Menu Bar: When a user clicks on a link in the header menu
• Footer links: When a user clicks on a link within the footer

[!NOTE] All links are automatically tracked. But if you need to track a button, your element needs to have a specific attributes "data-nav" and "data-link"(e.g: Next) [!NOTE]

Form Response Tracker

Trigger by the submission of any form, this tracker will send to GA4 some data about the form details:

• Type of field
• Label of the field
• Submit Button text
• Value of the field

Checkbox or Radio Fields Without a Legend

If a checkbox or radio field has been implemented without a legend, please follow these steps to ensure the tracker can retrieve the correct section value:

1. Add a rel attribute to the tag used to hold the section title.
2. Set the rel attribute value to match the id of the field.

Example: (

Section Title

Checkbox Label

)

Form Change Tracker

Form Change Tracker is triggered when a user clicks on a link that allows them to change a previous form they had completed and loads the form page correctly. The URL needs to contain an edit parameter equal to true (example: /my-form-page?edit=true). We are tracking the label of the field and the submit button text.

Form Error Tracker

Form Error Tracker is triggered when a page loads and when the page displays any form errors. We are tracking the label of the field and the error message.

Checkbox or Radio Fields Without a Legend

If a checkbox or radio field has been implemented without a legend, please follow these steps to ensure the tracker can retrieve the correct section value:

1. Add a rel attribute to the tag used to hold the section title.
2. Set the rel attribute value to match the id of the field.

Example: (

Section Title

Checkbox Label

)

Universal Analytics compability

More information: https://govukverify.atlassian.net/wiki/spaces/DIFC/pages/3843227661/Universal+Analytics+compatibility

(back to top)