Clean up the GA4 docs

docs/analytics-ga4/analytics.md

@@ -2,9 +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. For more information, see our [consent](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/analytics-ga4/consent.md) documentation.
+No analytics code is initialised and no data is gathered without user consent. For more information, see our [consent](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).
+If you are a developer working on a part of GOV.UK that includes analytics, read our [developer guide](developer-guide.md).
 
 ## General approach
 
@@ -20,7 +20,7 @@ Events happen when a user interacts with certain things, for example clicking on
 
 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).
+For more information about different kinds of tracking, read our [overview of trackers](trackers.md).
 
 ## Code structure
 
@@ -64,7 +64,7 @@ While our aim is to keep the majority of the analytics code in `govuk_publishing
 
 ### Code in components
 
-Often tracking will need to be built into components, either using an [existing tracker](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/analytics-ga4/ga4-all-trackers.md) or some custom code, or a combination of both.
+Often tracking will need to be built into components, either using an [existing tracker](trackers.md) or some custom code, or a combination of both.
 
 Where component tracking needs additional data to be passed (for example `index` or `section` values to show where the component is on a page) this should be built into the component and the data required documented in the component guide.
 
@@ -91,7 +91,7 @@ All of the data sent to GTM is based on a common schema.
 
 `search_results` is defined in the [ga4-ecommerce-tracker script](https://github.com/alphagov/govuk_publishing_components/blob/main/app/assets/javascripts/govuk_publishing_components/analytics-ga4/ga4-ecommerce-tracker.js).
 
-For more details of how our data schemas work, read our [data schemas documentation](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/analytics-ga4/ga4-schemas.md) or for the structure read our [Implementation record](https://docs.publishing.service.gov.uk/analytics/).
+For more details of how our data schemas work, read our [data schemas documentation](schemas.md) or for the structure read our [Implementation record](https://docs.publishing.service.gov.uk/analytics/).
 
 ## How the dataLayer works
 

docs/analytics-ga4/developer-guide.md

@@ -1,12 +1,6 @@
 # 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.
+The following is intended for developers working on a part of GOV.UK that includes analytics. If you are a GOV.UK developer looking to use our analytics code in your Rails application, read our [installation guide](developer-installation.md).
 
 ## Testing and debugging
 
@@ -20,6 +14,20 @@ 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.
 
+## 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](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.
+
+## Creating tracking
+
+A number of trackers already exist for a variety of situations. See the [list of GA4 trackers](trackers.md) to see what might be useful.
+
+Many components already include built in tracking. See the section `Components and tracking` in this document for more details.
+
+All of our tracking is based on [existing schemas](schemas.md). If you are creating new tracking you may need to extend the schemas to include new attributes. Check with a performance analyst for guidance on naming and other conventions. The data included in our events is documented in our [implementation record](https://docs.publishing.service.gov.uk/analytics/), which must be updated to reflect any changes.
+
 ## 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:

docs/analytics-ga4/developer-installation.md

@@ -0,0 +1,34 @@
+# Using our GA4 tracking in your application
+
+If you are a developer on GOV.UK looking to integrate the tracking code into one of our Rails applications there are several steps needed.
+
+The code in this gem is set up to track and structure data in a very specific way. If you wish to use a different [data schema](schemas.md) or track different things it may be easier to implement GA4 in a different way. Ask in the `#govuk-ga4` slack channel for advice.
+
+## Installation
+
+Ensure the gem is [installed in your application](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/install-and-use.md).
+
+Include the gem dependencies in your main JavaScript file: `//= require govuk_publishing_components/dependencies`.
+
+Add this meta tag to your main page template: `<meta name="govuk:components_gem_version" content="<%= GovukPublishingComponents::VERSION %>" />` (the gem version number is read from here for versioning purposes in the analytics data).
+
+Configure the GTM variables for your site as described in 'Passing extra options' in the [load analytics documentation](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/load-analytics.md), and include the `load-analytics.js` script in your code.
+
+If your application does not require cookie consent from your users, you will need to 'force' cookie consent to occur, as the analytics code depends upon it.
+
+```JavaScript
+window.GOVUK.approveAllCookieTypes()
+window.GOVUK.cookie('cookies_preferences_set', 'true', { days: 365 })
+```
+
+If your application already has a cookie banner and it is not the one from this gem, you will need to switch to ours.
+
+## Testing
+
+Once the code is configured correctly, data will start to be pushed to the dataLayer. Read the 'Testing and debugging' section of the [developer guide](developer-guide.md) to see how to check it is working correctly.
+
+Page views and some link tracking should happen automatically. Some components also track automatically. If you wish to add new tracking, start with the 'Creating tracking' section of the developer guide.
+
+## Configuring GTM/GA4
+
+Even if all of the above has worked correctly some configuration will still need to be done at the GTM/GA4 level to actually collect and store the analytics data. Talk to a performance analyst or ask in `#govuk-ga4` for more information.

docs/analytics-ga4/trackers.md

@@ -0,0 +1,52 @@
+# Trackers
+
+For tracking different kinds of data on GOV.UK we have built several different trackers. Each type of tracking is handled by a separate script, but some code is shared between them as they often do similar things.
+
+Most of the trackers work by adding a `data-module` attribute to an element along with additional data attributes to provide specific tracking information. Some components have this already built into their code by default. These components should also include a `disable_ga4` option as a failsafe.
+
+## Auto tracker
+
+The [auto tracker](trackers/ga4-auto-tracker.md) is used to cause an event to occur as soon as a page has finished loading (but after a page view). This is used to track significant moments in journeys, such as the successful completion of a smart answer, or an error.
+
+## Copy tracker
+
+The [copy tracker](trackers/ga4-copy-tracker.md) fires an event when text is copied from a page.
+
+## Ecommerce tracker
+
+The [ecommerce tracker](trackers/ga4-ecommerce-tracker.md) is used to track things like search results within a finder.
+
+## Event tracker
+
+The [event tracker](trackers/ga4-event-tracker.md) handles tracking on buttons or other interactive elements, such as tabs and details elements.
+
+## Focus loss tracker
+
+The [focus loss tracker](trackers/ga4-focus-loss-tracker.md) is designed to capture data about an element when it loses focus.
+
+## Form tracker
+
+The [form tracker](trackers/ga4-form-tracker.md) is designed to capture data about a form when it has been submitted.
+
+## Link tracker
+
+There are several types of link tracking. To distinguish them and simplify the code, we define them as follows.
+
+- the [link tracker](trackers/ga4-link-tracker.md) handles link clicks with data attributes added to specific links, or to parent elements of groups of links
+- the [specialist link tracker](trackers/ga4-specialist-link-tracker.md) automatically tracks clicks on 'special' links, such as external links, download links and mailto links
+
+## Print intent tracker
+
+The [print intent tracker](trackers/ga4-print-intent-tracker.md) tracks if the page has been requested to be printed.
+
+## Scroll tracker
+
+The [scroll tracker](trackers/ga4-scroll-tracker.md) tracks how much of a page has been viewed.
+
+## Smart answer results tracker
+
+The [smart answer results tracker](trackers/ga4-smart-answer-results-tracker.md) has been built specifically to track the Cost of Living smart answer.
+
+## Video tracker
+
+The [video tracker](trackers/ga4-video-tracker.md) tracks video views.