## 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
```sh
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:
```js
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:
```js
```
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:
```js
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:
```js
window.DI.analyticsGa4.cookie.hasConsentForAnalytics();
```
2/ You can revoke analytics cookie consent by calling the function setBannerCookieConsent:
```js
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:
```js
window.DI.analyticsGa4.pageViewTracker.trackOnPageLoad({
statusCode: 200,
englishPageTitle: "english version of the page title",
taxonomy_level1: "test tax1",
taxonomy_level2: "test tax2",
content_id: "",
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: ) [!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
)
### 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
)
### Universal Analytics compability
More information:
https://govukverify.atlassian.net/wiki/spaces/DIFC/pages/3843227661/Universal+Analytics+compatibility
---
_Source: https://npm.io/package/@govuk-one-login/one-login-analytics · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._