diff --git a/docs/analytics-ga4/analytics.md b/docs/analytics-ga4/analytics.md index 7114b6367c..f5ca802b47 100644 --- a/docs/analytics-ga4/analytics.md +++ b/docs/analytics-ga4/analytics.md @@ -2,7 +2,9 @@ This document describes the use of Google Tag Manager (GTM) with Google Analytics 4 (GA4) on GOV.UK Publishing. Further information can be found in our [Implementation record](https://docs.publishing.service.gov.uk/analytics/). -No analytics code is initialised and no data is gathered without user consent. +No analytics code is initialised and no data is gathered without user consent. For more information, see our [consent](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/analytics-ga4/consent.md) documentation. + +If you are a developer working on a part of GOV.UK that includes analytics, read our [developer guide](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/analytics-ga4/developer-guide.md). ## General approach @@ -20,24 +22,6 @@ Search data is gathered when users perform a search. For more information about different kinds of tracking, read our [overview of trackers](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/analytics-ga4/ga4-all-trackers.md). -## Cookie consent - -The analytics code is only loaded if users consent to cookies. This is managed by the `init-ga4.js` script. - -If the page loads and cookie consent has already been given, the analytics code is initialised. This includes sending a page view and creating any event listeners for analytics code such as link tracking. - -If the page loads and cookie consent has not been given, an event listener is created for the `cookie-consent` event, which is dispatched by the [cookie banner component](https://github.com/alphagov/govuk_publishing_components/pull/2041/commits/777a381d2ccb67f0a7e78ebf659be806d8d6442d). If triggered, the event listener will initialise the analytics code as described above. This allows analytics to begin on the page where the user consents to cookies. - -## Testing and debugging - -There is a [browser console command](https://github.com/alphagov/govuk_publishing_components/blob/00d81931a46e9826f07b939e0957ebc34d37f9ce/app/assets/javascripts/govuk_publishing_components/analytics-ga4/ga4-core.js#L36-L38) to assist with debugging. Enter the following in your browser console to show the data of analytics events when they occur. - -``` -window.GOVUK.analyticsGa4.showDebug = true -``` - -This is useful for seeing what is being pushed to the dataLayer for in-page events such as tabs or accordions. Enabling 'Preserve log' in Chrome will allow link click and other page reload events to be seen, but the command will need to be run again after a page reload to see subsequent event data. - ## Code structure It is important that no analytics code runs until cookie consent is given. Code to be initialised as part of cookie consent should be attached to the `window.GOVUK.analyticsGa4.analyticsModules` object and include an `init` function, using the structure shown below. diff --git a/docs/analytics-ga4/consent.md b/docs/analytics-ga4/consent.md new file mode 100644 index 0000000000..f16770c06e --- /dev/null +++ b/docs/analytics-ga4/consent.md @@ -0,0 +1,7 @@ +# GA4 and cookie consent + +The analytics code is only loaded if users consent to cookies. This is managed by the `init-ga4.js` script. + +If the page loads and cookie consent has already been given, the analytics code is initialised. This includes sending a page view and creating any event listeners for analytics code such as link tracking. + +If the page loads and cookie consent has not been given, an event listener is created for the `cookie-consent` event, which is dispatched by the [cookie banner component](https://github.com/alphagov/govuk_publishing_components/pull/2041/commits/777a381d2ccb67f0a7e78ebf659be806d8d6442d). If triggered, the event listener will initialise the analytics code as described above. This allows analytics to begin on the page where the user consents to cookies. diff --git a/docs/analytics-ga4/developer-guide.md b/docs/analytics-ga4/developer-guide.md new file mode 100644 index 0000000000..e533a8b48b --- /dev/null +++ b/docs/analytics-ga4/developer-guide.md @@ -0,0 +1,75 @@ +# GA4 developer guide + +The following is intended for developers working on a part of GOV.UK that includes analytics. + +## Identifying tracking + +Anything relating to GA4 will be prefixed with `ga4-`. This includes `data-ga4` attributes and module names. If you are modifying code that contains or is inside anything with a `ga4-` prefix you should check that the tracking still works after your change. + +Tracking is normally initialised on an element with a `data-module` for a [tracker](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/analytics-ga4/ga4-all-trackers.md) accompanied by a `data-ga4-(something)` attribute either on the same element or child elements. This attribute will usually contain a JSON snippet of data that will be picked up by the tracker and passed to GA4. See individual tracker documentation for more details. + +## Testing and debugging + +To see what events have already occurred on a page, type `window.dataLayer` into the browser console. + +To see events as they occur for the current page only, there is a [browser console command](https://github.com/alphagov/govuk_publishing_components/blob/00d81931a46e9826f07b939e0957ebc34d37f9ce/app/assets/javascripts/govuk_publishing_components/analytics-ga4/ga4-core.js#L36-L38) to assist with debugging. Enter the following in your browser console. + +``` +window.GOVUK.analyticsGa4.showDebug = true +``` + +This is useful for seeing what is being pushed to the dataLayer for in-page events such as tabs or accordions. Enabling 'Preserve log' in Chrome will allow link click and other page reload events to be seen, but the command will need to be run again after a page reload to see subsequent event data. + +## Components and tracking + +Many of [our components](https://components.publishing.service.gov.uk/component-guide) have GA4 tracking built in and enabled by default. This can be either: + +- all of the tracking for the component can be determined automatically and is handled entirely by the component +- most of the tracking can be determined automatically, but some extra parameters may need to be passed + +An example of the latter is the [Details component](https://components.publishing.service.gov.uk/component-guide/details#with_ga4_tracking). + +When a component includes tracking it should always be possible to disable this by passing a `disable_ga4` option to the component. + +## Understanding indexes + +Often GA4 events will include index attributes. These are used by analysts to understand where on a page an event originates. Indexes can be applied to any element but are most often seen when tracking links. All indexes start at 1. The index attributes are: + +- `index_link` should be the index of the link within this group of links +- `index_section` should be the index of this group of links, within groups of links in this part of the page +- `index_section_count` should be the total number of groups of links in this part of the page +- `index_total` should be the number of links within this group + +If you are adding or removing links to a part of a page where indexes are used for tracking, you may need to update the values accordingly. If you're uncertain, speak to a performance analyst. + +Here's a simplified example. + +```HTML +

Guidance on cheese

+ + +

Popular links

+ +```