YouTube Tracking

Snowplow Media Tracking

This plugin will allow the tracking of an embedded YouTube IFrame.

Tracker Distribution	Included
`sp.js`	❌
`sp.lite.js`	❌

Download

Download from GitHub Releases (Recommended)	Github Releases (plugins.umd.zip)
Available on jsDelivr	jsDelivr (latest)
Available on unpkg	unpkg (latest)

Note: This plugin will not work if using GAv4 Enhanced Measurement Video engagement, as both the GAv4 and Snowplow trackers will attempt to attach to the Youtube video.

Quick Start

The snippets below show how to get started with the plugin, after setting up your tracker.

The plugin's id attribute will accept:

The id of an iframe element
An existing instance of YT.Player, created with the YouTube Iframe API

Iframe
YT.Player Instance

<!DOCTYPE html>
<html>
  <body>
    <iframe
      id="yt-player"
      src="https://www.youtube.com/embed/zSM4ZyVe8xs"
    ></iframe>  

    <script>
      window.snowplow(
        'addPlugin',
        'https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-youtube-tracking@latest/dist/index.umd.min.js',
        ['snowplowYouTubeTracking', 'YouTubeTrackingPlugin']
      );

      window.snowplow('enableYouTubeTracking', {
        id: 'yt-player'
      });
    </script>
  </body>
</html>

<!DOCTYPE html>
<html>
  <body>
    <div id="yt-player"></div>

    <script>
      window.snowplow(
        'addPlugin',
        'https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-youtube-tracking@latest/dist/index.umd.min.js',
        ['snowplowYouTubeTracking', 'YouTubeTrackingPlugin']
      );

      const player = new YT.Player('yt-player', {
        videoId: 'zSM4ZyVe8xs'
      });

      window.snowplow('enableYouTubeTracking', {
          id: player
      });
    </script>
  </body>
</html>

The enableYouTubeTracking function

The enableYouTubeTracking function takes the form:

window.snowplow("enableYouTubeTracking", { id, options?: { label?, captureEvents?, boundaries?, updateRate? } })

Parameter	Type	Default	Description	Required
`id`	`string` or `YT.Player`	-	The HTML id attribute of the media element, or an instance of `YT.Player`	Yes
`options.label`	`string`	-	An identifiable custom label sent with the event	No
`options.captureEvents`	`string[]`	`["DefaultEvents"]`	The events or Event Group to capture. For a full list of events and groups, check the section below	No
`options.boundaries`	`number[]`	`[10, 25, 50, 75]`	The progress percentages to fire an event at (valid values 1 - 99 inclusive) [1]	No
`options.updateRate`	`number`	`250`	The rate at which `seek` and `volumechange` events can occur [2]	No

Below is an example of the full enableYouTubeTracking function:

window.snowplow('enableYouTubeTracking', {
  id: 'example-video',
  options: {
    label: 'My Custom Video Label',
    captureEvents: ['play', 'pause', 'ended'],
    boundaries: [20, 80],
    updateRate: 500,
  }
})

Events

Capturable Events

Below is a table of all the events that can be used in options.captureEvents

Name	Fire Condition
play	The video is played
pause	The video is paused
seek	On seek
volumechange	Volume has changed
ended	When playback stops at the end of the video
error	An error occurs in the player
percentprogress	When a percentage boundary set in `options.boundaries` is reached
playbackratechange	Playback rate has changed
playbackqualitychange	Playback quality has changed

Event Groups

You can also use a pre-made event group in options.captureEvents:

Name	Events
`DefaultEvents`	`["play", "pause", "seek", "volumechange", "ended", "percentprogress", "playbackratechange", "playbackqualitychange"]`
`AllEvents`	Every event listed in Capturable Events

It is possible to extend an event group with any event in the Events table above. This could be useful if you want, for example, all the events contained in the "DefaultEvents" group, along with the "error" event. This is expressed in the following way:

window.snowplow('enableYouTubeTracking', {
  id: "example-video",
  options: {
    captureEvents: ["DefaultEvents", "error"],
  }
})

Schemas and Example Data

Three schemas are used with this plugin:

An unstructured event with identifying information

{
    "type": "play",
    "label": "Identifying Label"
}

Snowplow platform-agnostic media context

{
    "currentTime": 12.32,
    "duration": 20,
    "ended": false,
    "loop": false,
    "muted": true,
    "paused": false,
    "playbackRate": 1,
    "volume": 100
}

YouTube player specific context

{
  "autoPlay": false,
  "avaliablePlaybackRates": [
    0.25, 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2
  ],
  "buffering": false,
  "controls": true,
  "cued": false,
  "loaded": 17,
  "playbackQuality": "hd1080",
  "playerId": "youtube",
  "unstarted": false,
  "url": "https://www.youtube.com/watch?v=zSM4ZyVe8xs",
  "yaw": 0,
  "pitch": 0,
  "roll": 0,
  "fov": 100.00004285756798,
  "avaliableQualityLevels": [
    "hd2160",
    "hd1440",
    "hd1080",
    "hd720",
    "large",
    "medium",
    "small",
    "tiny",
    "auto"
  ]
}

To track when a video ends, use the "ended" event.
seek and volumechange use setInterval to poll the player every n ms. You are able to adjust the poll rate, however, lower values may cause performance issues.

Snowplow Media Tracking

Download​

Quick Start​

The enableYouTubeTracking function​

Events​

Capturable Events​

Event Groups​

Schemas and Example Data​

An unstructured event with identifying information​

Snowplow platform-agnostic media context​

YouTube player specific context​