Monitor dash.js with the Mux Data SDK | Mux

Monitor dash.js

Connect Mux Data to dash.js to collect playback performance metrics. Use this guide when your web application plays MPEG-DASH video with dash.js.

In this guide:

Mux Data collects playback performance metrics from dash.js. Use this guide when your web application plays video with dash.js and you want to monitor the playback experience of your viewers. 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 Dash.js SDK, as described below.

Supported Features:

Engagement metrics
Quality of Experience Metrics
Web metrics such as Player Startup Time, Page Load Time, etc
Can infer CDN identification from response headers
Custom Dimensions
Average Bitrate metrics and renditionchange events
Request metrics
Customizable Error Tracking
Custom Beacon Domain

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.

2 Initialize Mux Data

Get your ENV_KEY from the Mux environments dashboard.

Env Key is different than your API token

ENV_KEY is a client-side key used for Mux Data monitoring. These are not to be confused with API tokens which are created in the admin settings dashboard and meant to access the Mux API from a trusted server.

Call mux.monitor and pass in a valid CSS selector or the video element itself. Followed by the SDK options and metadata. If you use a CSS selector that matches multiple elements, the first matching element in the document will be used.

In the SDK options, be sure to pass in the dashjs player instance.

Alternatively, if your player does not immediately have access to the dash.js player instance, you can start monitoring dash.js at any time in the future. In order to do this, you can call either of the following:

3 Make your data actionable

The only required field in the options that you pass into mux-embed is env_key. But without some metadata the metrics in your dashboard will lack the necessary information to take meaningful actions. Metadata allows you to search and filter on important fields in order to diagnose issues and optimize the playback experience for your end users.

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

For more information, view Make your data actionable.

4 Set or update metadata after initialization

There are some cases where you may not have the full set of metadata until after the video playback has started. 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 need to be reset:

New source: When you load a new source URL into an existing player.
New program: When the program within a singular stream changes (such as a program change within a continuous live stream).

New source

If your application plays multiple videos back-to-back in the same video player, you need to signal when a new video starts to the Mux SDK. Examples of when this is needed are:

The player advances to the next video in a playlist
The user selects a different video to play

New program

In some cases, you may have the program change within a stream, and you may want to track each program as a view on its own. An example of this is a live stream that streams multiple programs back to back, with no interruptions.

In this case, you emit a programchange event, including the updated metadata for the new program within the continuous stream. This will remove all previous video data and reset all metrics for the video view, creating a new video view.

6 Advanced options

Disable cookies

By default, Mux plugins for HTML5-based players use a cookie to track playback across subsequent page views in order to understand viewing sessions. This cookie includes information about the tracking of the viewer, such as an anonymized viewer ID that Mux generates for each user. None of this information is personally-identifiable, but you can disable the use of this cookie if desired. This is done by setting disableCookies: true in the options.

Over-ride 'do not track' behavior

By default, Mux plugins for HTML5-based players do not respect Do Not Track when set within browsers. This can be enabled in the options passed to Mux, via a setting named respectDoNotTrack. The default for this is false. If you would like to change this behavior, pass respectDoNotTrack: true.

Customize error tracking behavior

Errors are fatal. Errors tracked by mux are considered fatal meaning that they are the result of playback failures. If errors are non-fatal they should not be captured.

By default, mux-embed will track errors emitted from the video element as fatal errors. If a fatal error happens outside of the context of the player, you can emit a custom error to the mux monitor.

To make error aggregation as useful as possible, values provided should be general enough to provide useful information but not specific to each individual error.

Error translator

If your player emits error events that are not fatal to playback or the errors are unclear and/or do not have helpful information in the default error message and codes you might find it helpful to use an error translator or disable automatic error tracking all together.

Disable automatic error tracking

In the case that you want full control over what errors are counted as fatal or not, you may want to consider turning off Mux's automatic error tracking completely. This can be done by passing automaticErrorTracking: false in the configuration object.

Use TypeScript with mux-embed Beta

mux-embed now provides TypeScript type definitions with the published package! If you want to opt in, you can check out how here.

Customize beacon collection domain

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

Release notes

Current release

v5.18.2

Fix crash on load ("Cannot read properties of undefined (reading 'performance')") when the host page sets window.__esModule

Previous releases

v5.18.1

chore: replace build and deploy setup (no functional changes)

v5.18.0

Set viewer_connection_type, viewer_connection_low_data_mode with new networkchange event

v5.17.10

[chore] force upgrade of yarn to 4.12.0

v5.17.9

[chore] upgrade yarn version

v5.17.8

[chore] publish mux-embed first, then the rest

v5.17.7

fix workspace build issue

v5.17.6

[chore] fix release pipeline

v5.17.5

fix issue where playback_mode may not have appeared on all events

v5.17.4

[chore] fix npm publish

v5.17.3

[chore] fix deploy pipeline

v5.17.2

[chore] update build process to github actions

v5.17.1

fix issue where playing time might accumulate for paused players

v5.17.0

add compatibility for dash.js 5

v5.16.1

Update parsing of initial value for player_playback_mode

v5.16.0

Add Playback Range Tracker for new engagement metrics

v5.15.0

Automatically detect playback mode changes for HTML 5 Video

v5.14.0

Emit a renditionchange event at the start of views to enable updated rendition tracking.

v5.13.0

Add ad type metadata to Ad Events