Skip to main content

YouTube iFrame media tracking

This plugin enables the automatic tracking of an embedded YouTube iFrame video, using the Snowplow Media Plugin and YouTube Player API.

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)

Quick Start​

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

startYouTubeTracking​

This function enables the auto tracking for the specified YouTube Player. It installs the iFrame API if necessary, adds event listeners and any poll intervals, and then calls startMediaTracking.

The accepted options are the same as for the core startMediaTracking method, with the following additions:

  • video: A DOM ID for the iFrame element hosting the player, an iFrame element, or a pre-existing YT.Player instance to track events for.
  • captureEvents: An optional list of events to track; see Events.
  • label: The plugin manages the player entity automatically, but you can optionally supply a custom label if required.

As it is required for startMediaTracking, the following option is also required:

  • id: A UUID used to identify the media session the events will be a part of.

Other options such as updatePageActivityWhilePlaying will be passed to the core plugin directly.

The function returns the mediaSessionId used for the events that will be generated; this value can be passed to endYouTubeTracking.

<!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']
      );

      var mediaSessionId = crypto.randomUUID();

      window.snowplow('startYouTubeTracking', {
        id: mediaSessionId,
        video: 'yt-player' // or: document.getElementById('yt-player')
      });
    </script>
  </body>
</html>

endYouTubeTracking​

This function disables auto tracking for the player registered with the provided session ID.

It will remove any event listeners and poll intervals, and call endMediaTracking from the core plugin.

<!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']
      );

      var mediaSessionId = crypto.randomUUID();

      window.snowplow('startYouTubeTracking', {
        id: mediaSessionId,
        video: 'yt-player' // or: document.getElementById('yt-player')
      });

      window.snowplow('endYouTubeTracking', mediaSessionId);
    </script>
  </body>
</html>

trackYouTubeSelfDescribingEvent​

This function allows tracking custom Self Describing Event payloads that have the media-related entities attached as if they were generated by this or the core plugin directly.

<!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']
      );

      var mediaSessionId = crypto.randomUUID();

      window.snowplow('startYouTubeTracking', {
        id: mediaSessionId,
        video: 'yt-player' // or: document.getElementById('yt-player')
      });

      window.snowplow('trackYouTubeSelfDescribingEvent', {event: {schema: 'iglu:com_example/my_event/jsonschema/1-0-0', data: { video: true }}});

      window.snowplow('endYouTubeTracking', mediaSessionId);
    </script>
  </body>
</html>

Events​

Capturable Events​

Below is a table of all the core Snowplow Media plugin events that can be used in the captureEvents option:

NameFire Condition
readyThe video player has loaded
playThe video is played
pauseThe video is paused
endWhen playback stops at the end of the video
seek_startWhen seeking begins to jump to another position of the video
seek_endWhen seeking ends and another position of the video is jumped to
playback_rate_changePlayback rate has changed
volume_changeVolume has changed
pingFires periodically during playback
percent_progressFires at progress milestones defined by boundaries option
buffer_startFires when playback pauses because content is not yet buffered
buffer_endFires when playback resumes after content has been fetched
quality_changePlayback quality has changed
errorAn error occurs in the player

In addition, the following event names are also accepted for compatibility with v3, mapped to the equivalent event from above:

NameFire Condition
seekOn seek
volumechangeVolume has changed
endedWhen playback stops at the end of the video
percentprogressWhen a percentage boundary set in options.boundaries is reached
playbackratechangePlayback rate has changed
playbackqualitychangePlayback quality has changed

The following events are defined by the core Snowplow Media plugin but not supported by this plugin or the YouTube API:

NameFire Condition
fullscreen_changeFull screen state toggled
picture_in_picture_changePicture-in-picture state toggled
ad_break_startBeginning of an ad break
ad_break_endEnd of an ad break
ad_startBeginning of an ad within an ad break
ad_first_quartile25% progress through an ad
ad_midpoint50% progress through an ad
ad_third_quartile75% progress through an ad
ad_complete100% progress through an ad
ad_skipUser has opted to skip the ad before completion
ad_clickUser has clicked the playing ad
ad_pauseUser has paused the playing ad
ad_resumeUser has resumed the paused ad

Event Groups​

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

NameEvents
DefaultEvents['ready', 'play', 'pause', 'ping', 'end', 'seek_start', 'seek_end', 'volume_change', 'percent_progress', 'playback_rate_change', 'quality_change']
AllEventsEvery supported 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('startYouTubeTracking', {
  id: crypto.randomUUID(),
  video: "example-video",
  captureEvents: ["DefaultEvents", "error"],
})

Legacy API​

In addition to the above, the following methods are provided for compatibility with earlier versions of the plugin.

These APIs are deprecated in v4, and wrap the newer API methods above.

The enableYouTubeTracking function​

enableYouTubeTracking is similar to startYouTubeTracking, except:

  • An id option is used to identify the player instead of video
  • The additional options to startMediaTracking are nested within an options object
  • The media session ID value will be generated automatically if not provided
The plugin's id option is equivalent to video in the new API and will accept:
  • The id of an iframe element
  • An iframe element directly
  • An existing instance of YT.Player, created with the YouTube Iframe API

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.*anyAny other options are passed through to startMediaTrackingNo

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,
  }
})

The disableYouTubeTracking function​

This function is an equivalent counterpart to endYouTubeTracking for enableYouTubeTracking.

Instead of requiring the session ID to be provided, it will remove the oldest of any sessions started with enableYouTubeTracking so the session ID doesn't need to be known and passed explicitly.

Schemas and Example Data​

Event and entity schemas are the same as for the Snowplow Media Plugin.

In addition, there is a dedicated entity attached with YouTube-specific information to all events.

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"
  ]
}