Skip to main content

HTML5 media tracking on web

This plugin enables the automatic tracking of HTML5 media elements (<video> and <audio>) on a webpage.

It uses the Snowplow Media plugin under the hood.

HTML5 media events and entities are automatically tracked once configured.

Install plugin​

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: The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production.

javascript
window.snowplow('addPlugin',
  "https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-media-tracking@latest/dist/index.umd.min.js",
  ["snowplowMediaTracking", "MediaTrackingPlugin"]
);

Quick Start​

To start tracking media with default settings:

main.js

html
<video id='html-id' src='./video.mp4'></video>
<script>
  window.snowplow('addPlugin',
    "https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-media-tracking@latest/dist/index.umd.min.js",
    ["snowplowMediaTracking", "MediaTrackingPlugin"]
  );

  const sessionId = crypto.randomUUID();

  window.snowplow('startHtml5MediaTracking', {
    id: sessionId,
    video: 'html-id',
  })
</script>

index.html

html
<video id='html-id' src='./video.mp4'></video>

Start tracking​

Start tracking HTML5 media by calling the startHtml5MediaTracking function with a configuration object. You must provide a unique id for the media session, along with the video ID.

javascript
window.snowplow('startHtml5MediaTracking', {
  id: "unique-session-id",
  video: "myVideoElement",
  label: "Product Demo Video",
  captureEvents: ["play", "pause", "end"],
  boundaries: [25, 50, 75, 100],
  pings: {
    pingInterval: 20,
    maxPausedPings: 2,
  },
  updatePageActivityWhilePlaying: true,
  filterOutRepeatedEvents: {
    seekEvents: true,
    volumeChangeEvents: false,
    flushTimeoutMs: 5000
  },
  session: {
    // Custom session start time
    startedAt: new Date('2024-01-01T12:00:00Z'),
  },
});
ParameterTypeDescriptionDefault / Required
idstringA unique session UUID for each media element, used to identify and end tracking.Required
videostring or HTMLMediaElementThe ID of the media element (as a string) or the media element itself.Required
labelstringA human-readable label for the media element.undefined
captureEventsHTML5MediaEventTypesA list of media events to track.All events tracked by default
boundariesnumber[]Percentage thresholds (0-100) to trigger progress events.[10, 25, 50, 75]
contextDynamicContextDynamic contexts attached to each tracking event.undefined
updatePageActivityWhilePlayingbooleanWhether to update page activity while media is playing.true
filterOutRepeatedEventsFilterOutRepeatedEventsWhether to suppress consecutive identical events.Enabled by default
filterOutRepeatedEvents .seekEventsbooleanWhether to filter out seek start and end events tracked after each other.true
filterOutRepeatedEvents .volumeChangeEventsbooleanWhether to filter out volume change events tracked after each other.true
filterOutRepeatedEvents .flushTimeoutMsnumberTimeout in milliseconds after which to send the events that are queued for filtering.5000 (milliseconds)
pings.pingIntervalnumberInterval (in seconds) for sending ping events.30 (seconds)
pings.maxPausedPingsnumberMaximum number of ping events sent while playback is paused.1
sessionboolean or objectWhether to track the media session entity for playback statistics, or set a custom start time.true

Stop tracking​

End tracking by calling endHtml5MediaTracking. 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.

main.js

html
<video id='html-id' src='./video.mp4'></video>
<script>
  window.snowplow('addPlugin',
    "https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-media-tracking@latest/dist/index.umd.min.js",
    ["snowplowMediaTracking", "MediaTrackingPlugin"]
  );

  const sessionId = crypto.randomUUID();

  window.snowplow('startHtml5MediaTracking', {
    id: sessionId,
    video: 'html-id',
  })

  // Tracking some video events...

  window.snowplow('endHtml5MediaTracking', sessionId)
</script>

Events​

The HTML5 media plugin can track the following events:

Event TypeEvent StringDescription
ReadyreadyFired when media tracking is successfully attached to the player and ready to track events.
PlayplayFired when the player transitions from a paused state to playing.
PausepauseFired when the user pauses the playback.
EndendFired when playback stops because the media has reached its end or no more data is available.
SeekEndseek_endFired when a seek operation is completed.
PlaybackRateChangeplayback_rate_changeFired when the playback rate (speed) of the media changes.
VolumeChangevolume_changeFired when the volume level of the media changes.
FullscreenChangefullscreen_changeFired when the browser enters or exits full-screen mode.
PictureInPictureChangepicture_in_picture_changeFired when the browser enters or exits picture-in-picture mode.
BufferStartbuffer_startFired when the media player starts buffering (loading content to play).
BufferEndbuffer_endFired when buffering ends, and playback resumes.
ErrorerrorFired when an error occurs during the loading or playback of the media.
PingpingFired periodically during media playback, regardless of other events.
PercentProgresspercent_progressFired when a specific percentage of the media content has been played (as set by boundaries).

It's possible to only track a subset of these events by passing an array of event types to the captureEvents option:

javascript
window.snowplow("startHtml5MediaTracking", {
  id: crypto.randomUUID(),
  video: 'example-video',
  captureEvents: ['play', 'pause'],
})

Additional entities​

The event and entity schemas are the same as for the Snowplow Media plugin.

Along with the standard Snowplow media entities, the HTML5 media plugin also tracks two HTML5 media-specific entities, media_element and video_element.

For <video> elements, both entities are added to all media events in the session. For <audio> elements, only the media_element entity is added.

If you've configured the Media Player dbt package to use the v1 schemas, or are using an older version of the Media Player model, it will use fields from the media_element and video_element entities. The Media Player model version 0.6+ doesn't use them.

HTML5 media element​

media_element

Entity
Context Schema for a media player event
Schema URIiglu:org.whatwg/media_element/jsonschema/1-0-0
Example
json
{
  "htmlId": "my-video",
  "mediaType": "VIDEO",
  "autoPlay": false,
  "buffered": [
    {
      "start": 0,
      "end": 20
    }
  ],
  "controls": true,
  "currentSrc": "http://example.com/video.mp4",
  "defaultMuted": true,
  "defaultPlaybackRate": 1,
  "disableRemotePlayback": false,
  "error": null,
  "networkState": "NETWORK_IDLE",
  "preload": "metadata",
  "readyState": "HAVE_ENOUGH_DATA",
  "seekable": [
    {
      "start": 0,
      "end": 20
    }
  ],
  "seeking": false,
  "src": "http://example.com/video.mp4",
  "textTracks": [
    {
      "label": "English",
      "language": "en",
      "kind": "captions",
      "mode": "showing"
    }
  ],
  "fileExtension": "mp4",
  "fullscreen": false,
  "pictureInPicture": false
}
Properties and schema
PropertyDescription
autoPlay
boolean		Required. If playback should automatically begin as soon as enough media is available to do so without interruption
buffered
array		Required. An array of time ranges that have been buffered
controls
boolean		Required. If the user agent should provide it's own set of controls
crossOrigin
string		Optional. CORS settings value of the media player
currentSrc
string		Required. The absolute URL of the media resource
defaultMuted
boolean		Required. If audio is muted by default
defaultPlaybackRate
number		Required. The default media playback rate of the player
disableRemotePlayback
boolean		Optional. If the media element is allowed to have a remote playback UI
error
object		Required. An object of the latest error to occur, or null if no errors
fileExtension
string		Optional. The media file format
fullscreen
boolean		Optional. If the video element is fullscreen
mediaType
string		Required. If the media is a video element, or audio
Must be one of: AUDIO, VIDEO
networkState
string		Required. The current state of the fetching of media over the network
Must be one of: NETWORK_EMPTY, NETWORK_IDLE, NETWORK_LOADING, NETWORK_NO_SOURCE
pictureInPicture
boolean		Optional. If the video element is showing Picture-In-Picture
played
array		Optional. An array of time ranges played
htmlId
string		Required. The HTML id of the element
preload
string		Required. The 'preload' HTML attribute of the media
readyState
string		Required. The readiness of the media
Must be one of: HAVE_NOTHING, HAVE_METADATA, HAVE_CURRENT_DATA, HAVE_FUTURE_DATA, HAVE_ENOUGH_DATA
seekable
array		Required. Seekable time range(s)
seeking
boolean		Required. If the media is in the process of seeking to a new position
src
string		Optional. The 'src' HTML attribute of the media element
textTracks
array		Optional. An array of TextTrack objects on the media element

HTML5 video element​

video_element

Entity
Context Schema for a video player event
Schema URIiglu:org.whatwg/video_element/jsonschema/1-0-0
Example
json
{
  "autoPictureInPicture": false,
  "disablePictureInPicture": false,
  "poster": "http://www.example.com/poster.jpg",
  "videoHeight": 300,
  "videoWidth": 400
}
Properties and schema
PropertyDescription
autoPictureInPicture
boolean		Optional. A boolean value that is true if the video should enter or leave picture-in-picture mode automatically when changing tab and/or application
disablePictureInPicture
boolean		Optional. The disablePictureInPicture property will hint the user agent to not suggest the picture-in-picture to users or to request it automatically
poster
string		Optional. 'poster' HTML attribute, which specifies an image to show while no video data is available
videoHeight
integer		Required. A value indicating the intrinsic height of the resource in CSS pixels, or 0 if no media is available yet
videoWidth
integer		Required. A value indicating the intrinsic width of the resource in CSS pixels, or 0 if no media is available yet

On this page

Want to see a custom demo?

Our technical experts are here to help.

Book a demo