Skip to main content
caution
You are reading documentation for an outdated version. Here’s the latest one!

YouTube iFrame media tracking

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

YouTube media events and entities are automatically tracked once configured.

Installation​

Tracker DistributionIncluded
sp.js❌
sp.lite.js❌

Download:

Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (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
  1. iFrame

For this plugin to find your media element, your iFrame must be given the id that is passed into enableYouTubeTracking.

<!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@3/dist/index.umd.min.js',
        ['snowplowYouTubeTracking', 'YouTubeTrackingPlugin']
      );

      window.snowplow('enableYouTubeTracking', {
        id: 'yt-player'
      });
    </script>
  </body>
</html>
  1. YT.Player
<!DOCTYPE html>
<html>
  <body>
    <div id="yt-player"></div>

    <script>
      window.snowplow(
        'addPlugin',
        'https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-youtube-tracking@3/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? } })
ParameterTypeDefaultDescriptionRequired
idstring or YT.Player-The HTML id attribute of the media elementYes
options.labelstring-An identifiable custom label sent with the eventNo
options.captureEventsstring[]['DefaultEvents']The events or Event Group to capture. For a full list of events and groups, check the section belowNo
options.boundariesnumber[][10, 25, 50, 75]The progress percentages to fire an event at (valid values 1 - 99 inclusive) [1]No
options.updateRatenumber250The 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

NameFire Condition
playThe video is played
pauseThe video is paused
seekOn seek
volumechangeVolume has changed
endedWhen playback stops at the end of the video
errorAn error occurs in the player
percentprogressWhen a percentage boundary set in options.boundaries is reached
playbackratechangePlayback rate has changed
playbackqualitychangePlayback quality has changed

Event Groups​

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

NameEvents
DefaultEvents['play', 'pause', 'seek', 'volumechange', 'ended', 'percentprogress', 'playbackratechange', 'playbackqualitychange']
AllEventsEvery 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": "example-id",
  "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"
  ]
}

  1. To track when a video ends, use the 'ended' event.

  2. 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.