Update docs

- add docs for video tracker
- update changelog

CHANGELOG.md

@@ -17,6 +17,7 @@
 * Add section attribute to scroll tracking ([PR #3537](https://github.com/alphagov/govuk_publishing_components/pull/3537))
 * Add navigation-page-type GA4 pageview attribute ([PR #3529](https://github.com/alphagov/govuk_publishing_components/pull/3529))
 * Update the documentation for loading component stylesheets individually ([PR #3543](https://github.com/alphagov/govuk_publishing_components/pull/3543))
+* Add GA4 video tracking ([PR #3535](https://github.com/alphagov/govuk_publishing_components/pull/3535))
 
 ## 35.13.1
 

docs/analytics-ga4/ga4-video-tracker.md

@@ -0,0 +1,33 @@
+# Google Analytics 4 video tracker
+
+This script tracks interactions with videos on GOV.UK. It sends an event to the dataLayer when any of the following occur.
+
+- a video starts playing
+- a video reaches the end
+- a video gets to 25%, 50%, or 75% of the way through
+
+These events only fire once for each video on any given page. Below is an example of the data sent to the dataLayer for a specific video, on beginning of playback.
+
+```
+{
+  'event': 'event_data',
+  'event_data': {
+    'event_name': 'video_start',
+    'type': 'video',
+    'url': 'https://www.youtube.com/watch?v=TvHpBXB0q0Y',
+    'text': 'My first Self Assessment tax return',
+    'action': 'start',
+    'video_current_time': 0,
+    'video_duration': 152,
+    'video_percent': 0
+  }
+}
+```
+
+## How it works
+
+Assuming that consent has been given, the video tracker is launched automatically by the [Youtube link enhancement script](https://github.com/alphagov/govuk_publishing_components/blob/main/app/assets/javascripts/govuk_publishing_components/lib/govspeak/youtube-link-enhancement.js). Note that if cookie consent is not given, videos are not loaded on GOV.UK. Instead the user is shown a link to the video.
+
+The Youtube enhancement script creates an embedded Youtube player based on a link to a video. This includes the `enablejsapi` option, which is needed for tracking. The `onStateChange` event provided by the Youtube API allows code to be executed when a user interacts with a video, for example when playing or pausing.
+
+The function attached to this event listener calls the GA4 video tracker. Since there is no event fired during playback, in order to track progress (e.g. reaching 25%) an interval is created once a second, that checks progress using calls to the Youtube API. When it reaches one of the percentage positions it pushes information to the dataLayer and records that this event should not be fired again.