Skip to main content

HTML5 media tracking

This plugin enables the automatic tracking of HTML media elements (<video> and <audio>) on a webpage, using the Snowplow Media Plugin.

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.

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

<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

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

startHtml5MediaTracking​

This function begins tracking media events for a given media element. It takes a configuration object with the following fields:

Required Fields​

ParameterTypeDescription
config.idstringA unique session ID for each media element, used to identify and end tracking.
config.videostring \| HTMLMediaElementThe ID of the media element (as a string) or the media element itself.

Optional Fields​

ParameterTypeDescriptionDefault Value
config.labelstringA human-readable label for the media element.undefined
config.captureEventsHTML5MediaEventTypesA list of media events to track.All events tracked by default
config.boundariesnumber[]Percentage thresholds (0-100) to trigger progress events.Disabled
config.contextDynamicContextDynamic contexts attached to each tracking event.undefined
config.updatePageActivityWhilePlayingbooleanWhether to update page activity while media is playing.true
config.filterOutRepeatedEventsFilterOutRepeatedEventsWhether to suppress consecutive identical events.false

Ping Configuration (Optional)​

ParameterTypeDescriptionDefault Value
config.pings.pingIntervalnumberInterval (in seconds) for sending ping events.30 (seconds)
config.pings.maxPausedPingsnumberMaximum number of ping events sent while playback is paused.1

Filter Out Repeated Events Configuration (Optional)​

ParameterTypeDescriptionDefault Value
config.filterOutRepeatedEvents.seekEventsbooleanWhether to filter out seek start and end events tracked after each other.false
config.filterOutRepeatedEvents.volumeChangeEventsbooleanWhether to filter out volume change events tracked after each other.false
config.filterOutRepeatedEvents.flushTimeoutMsnumberTimeout in milliseconds after which to send the events that are queued for filtering.5000 (milliseconds)

Example Usage​

startHtml5MediaTracking({
  id: "unique-session-id",
  video: document.getElementById("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
  },
});

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

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

Customizing Tracked Events​

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

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

Schemas​

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

Along with the standard media context, the HTML5 media plugin also tracks the following media-specific contexts:

HTML5 Media specific context​

{
    "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": "IDLE",
    "preload": "metadata",
    "readyState": "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
}

HTML5 Video specific context​

{
    "autoPictureInPicture": false,
    "disablePictureInPicture": false,
    "poster": "http://www.example.com/poster.jpg",
    "videoHeight": 300,
    "videoWidth": 400
}