one-login-ga4 v0.0.22

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.

Getting Started

Installation

1. Install NPM package

   npm install one-login-ga4

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/one-login-ga4/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).

!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}}"})
    </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
   • disableAnalyticsCookie (boolean): disable analytics cookie logic within the analytics library
   • disableFormFreeTextTracking (boolean): disable free text field tracking within the form response tracker.

Example of call:

window.DI.appInit(
  { ga4ContainerId: "{{ga4ContainerId}}" },
  {
    disabldisableGa4Tracking: true,
    disableUaTracking: true,
    disableAnalyticsCookie: false,
    disableFormFreeTextTracking: true,
  },
);

!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

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

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

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.