Monitor HTML5 video element | Mux

Monitor HTML5 video element

Connect Mux Data to the HTML5 video element to collect playback performance metrics. Use this guide when your web application plays video without a player framework, or when Mux does not have an SDK for your player.

In this guide:

Features

The features supported by Mux Data for this player.

1 Install mux-embed

Install mux-embed either from our CDN or from the npm registry.

2 Initialize Mux Data

Attach mux-embed to your player so that Mux can collect playback metrics.

3 Make your data actionable

Use metadata fields to make the data collected by Mux actionable and useful.

4 Set or update metadata after initialization

If you do not have all the metadata available at initialization time update metadata fields later.

5 Changing the video

If your implementation changes the video without changing the video player, let mux-embed know to start tracking a new view.

6 Advanced options

Depending on the details of your implementation, you may want to leverage some of the advanced options of mux-embed.

Release notes

Mux Data collects playback performance metrics from the HTML5 <video> element. Use this guide when your web application plays video with the built-in HTML5 video element, or when Mux does not have an SDK for your specific player. You do not need Mux Video to use Mux Data.

Features

The following data can be collected by the Mux Data SDK when you use the HTML Video Element SDK, as described below.

Supported Features:

Notes:

Live Latency is available for Native Safari HLS.

1 Install mux-embed

Include the Mux JavaScript SDK on every page of your web app that includes video. You can use the Mux-hosted version of the script or install via npm. mux-embed follows semantic versioning and the API will not change between major releases.

If possible, use the SDK for your particular player (e.g. Video.js, JW Player, etc.). While the HTML5 SDK works with any modern HTML5 video player, the player-specific Mux SDK is preferable because it offers a deeper integration and in most cases collects more pieces of data. If you don't see your player listed then use mux-embed and let us know so we can prioritize creating an SDK for the player that you are using.

// Include the following script in your HTML
<script src="https://cdn.mux.com/mux-embed.min.js"></script>

2 Initialize Mux Data

Get your ENV_KEY from the Mux environments dashboard.

ENV_KEY is a client-side key used for Mux Data monitoring. These are not to be confused with API tokens.

mux.monitor('video-element', {
  env_key: 'YOUR_ENV_KEY',
  ... // additional options
});

3 Make your data actionable

Pass in metadata under the data key when calling mux.monitor.

4 Set or update metadata after initialization

In this case, you should omit the values when you first call monitor. Then, once you have the metadata, you can update the metadata with the updateData method.

5 Changing the video

There are two cases where the underlying tracking of the video view needs to be reset:

  1. New source: When you load a new source URL into an existing player.
  2. New program: When the program within a singular stream changes.

To signal the Mux SDK that a new view is starting, you will need to emit a videochange event, along with metadata about the new video.

player.emit('videochange', { video_id: newVideoId });

6 Advanced options

Disable cookies

By default, Mux plugins for HTML5-based players use a cookie to track playback across subsequent page views. You can disable the use of this cookie if desired.

mux.monitor('video-element', { disableCookies: true });

Over-ride 'do not track' behavior

You can enable respect for Do Not Track in the options passed to Mux.

mux.monitor('video-element', { respectDoNotTrack: true });

Customize error tracking behavior

When triggering an error event, it is important to provide values for player_error_code and player_error_message. The error message should provide a general description of the error as it happened.

Customize beacon collection domain

If you have integrated a custom domain for Data collection, specify your custom domain by setting beaconCollectionDomain.