This guide walks through integration with THEOplayer to collect video performance metrics with Mux Data.
Features
Install @mux/mux-data-theoplayer
@mux/mux-data-theoplayer
Initialize Mux Data
Make your data actionable
Set or update metadata after initialization
Changing the video
Advanced options
Release notes
The following data can be collected by the Mux Data SDK when you use the THEOplayer Web SDK, as described below.
Supported Features:
renditionchange
events@mux/mux-data-theoplayer
Include the Mux JavaScript SDK on every page of your web app that includes video.
npm install --save @mux/mux-data-theoplayer
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 new THEOplayer.Player
like you normally would. Call initTHEOplayerMux
with a reference to the player instance and the Mux SDK options.
import * as THEOplayer from 'theoplayer';
import initTHEOplayerMux from '@mux/mux-data-theoplayer';
const playerInitTime = initTHEOplayerMux.utils.now();
const playerWrapper = document.querySelector('#my-player');
// Get a reference to your player, and pass it to the init function
const player = new THEOplayer.Player(playerWrapper, {
// Insert player configuration here
});
player.src = 'https://muxed.s3.amazonaws.com/leds.mp4';
initTHEOplayerMux(player, {
debug: false,
data: {
env_key: 'ENV_KEY', // required
// Metadata
player_name: '', // ex: 'My Main Player'
player_init_time: playerInitTime // ex: 1451606400000
// ... and other metadata
}
}, THEOplayer);
THEOplayer
globalYou'll see the 3rd argument to initTHEOplayerMux
is THEOplayer
. This is the global THEOplayer
object. If you are using a bundler and importing THEOplayer
with require
or import
then you'll need to pass in the THEOplayer
object.
If no THEOplayer
object is passed in, then initTHEOplayerMux
will look for THEOplayer
on then global window
object.
The only required field in the options
that you pass into initTHEOplayerMux
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
on initialization.
// player here is the instance of THEOplayer.Player
initTHEOplayerMux(player, {
debug: false,
data: {
env_key: 'ENV_KEY', // required
// Site Metadata
viewer_user_id: '', // ex: '12345'
experiment_name: '', // ex: 'player_test_A'
sub_property_id: '', // ex: 'cus-1'
// Player Metadata
player_name: '', // ex: 'My Main Player'
player_version: '', // ex: '1.0.0'
player_init_time: '', // ex: 1451606400000
// Video Metadata
video_id: '', // ex: 'abcd123'
video_title: '', // ex: 'My Great Video'
video_series: '', // ex: 'Weekly Great Videos'
video_duration: '', // in milliseconds, ex: 120000
video_stream_type: '', // 'live' or 'on-demand'
video_cdn: '' // ex: 'Fastly', 'Akamai'
}
});
For more information, view Make your data actionable.
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 initTHEOplayerMux
. Then, once you have the metadata, you can update the metadata with the updateData
method.
// player is the instance of THEOplayer.Player
let monitor = initTHEOplayerMux(player, {
debug: false,
data: {
env_key: 'ENV_KEY', // required
video_id: 'abcd123',
}
});
monitor.updateData({ video_title: 'My Updated Great Video' });
There are two cases where the underlying tracking of the video view need to be reset:
Note: You do not need to change the video info when changing to a different source of the same video content (e.g. different resolution or video format).
For THEOplayer, you do not need to emit the videochange
event when the player source property of the player is updated. The sourcechange
event that is fired when you update the source property of the player is handled automatically. However, you still need to pass the updated video metadata under metadata.mux
, as shown in the example below.
When this is done, it removes all previous video data and resets all metrics for the video view. Note: the previous method using changeMuxVideo has been deprecated, but will continue to work for 2.x versions of this plugin.
player.source = {
sources: {
// ...your source
},
metadata: {
mux: {
video_id: 'new-ID',
video_title: 'New title',
// ... other metadata
}
}
}
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. See Metadata for the list of video details you can provide. You can include any metadata when changing the video but you should only need to update the values that start with video
.
Note: The programchange
event is intended to be used only while the player is currently not paused. If you emit this event while the player is paused, the resulting view will not track video startup time correctly, and may also have incorrect watch time. Do not emit this event while the player is paused.
// player is the instance of THEOplayer.Player
let monitor = initTHEOPlayerMux(player, {
debug: false,
data: {
env_key: "ENV_KEY",
// ...
}
});
// emit `programchange` when the content within the stream changes
monitor.emit('programchange', {
video_id: 'abc345',
video_title: 'My Other Great Video',
video_series: 'Weekly Great Videos',
// ...
});
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. For instance, if your site or application is targeted towards children under 13, you should disable the use of cookies. For information about the specific data tracked in the cookie, please refer to: What information is stored in Mux Data HTML cookies.
This is done by setting disableCookies: true
in the options.
// player here is the instance of THEOplayer.Player
initTHEOplayerMux(player, {
debug: false,
disableCookies: true,
data: {
env_key: "ENV_KEY",
// ...
}
});
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
.
// player is the instance of THEOplayer.Player
initTHEOplayerMux(player, {
debug: false,
respectDoNotTrack: true,
data: {
env_key: "ENV_KEY",
// ...
}
});
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/mux-data-theoplayer
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.
// player is the instance of THEOplayer.Player
let monitor = initTHEOPlayerMux(player, {
debug: false,
data: {
env_key: "ENV_KEY",
// ...
}
});
// emit the `error` event when an error occurs
monitor.emit('error', {
player_error_code: 100,
player_error_message: 'Description of error',
player_error_context: 'Additional context for the error'
});
When triggering an error event, it is important to provide values for player_error_code
and player_error_message
. The player_error_message
should provide a generalized description of the error as it happened. The player_error_code
must be an integer, and should provide a category of the error. If the errors match up with the HTML Media Element Error, you can use the same codes as the corresponding HTML errors. However, for custom errors, you should choose a number greater than or equal to 100
.
In general you should not send a distinct code for each possible error message, but rather group similar errors under the same code. For instance, if your library has two different conditions for network errors, both should have the same player_error_code
but different messages.
The error message and code are combined together and aggregated with all errors that occur in your environment in order to find the most common errors that occur. To make error aggregation as useful as possible, these values should be general enough to provide useful information but not specific to each individual error (such as stack trace).
You can use player_error_context
to provide instance-specific information derived from the error such as stack trace or segment-ids where an error occurred. This value is not aggregated with other errors and can be used to provide detailed information. Note: Please do not include any personally identifiable information from the viewer in this data.
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.
function errorTranslator (error) {
return {
player_error_code: translateCode(error.player_error_code),
player_error_message: translateMessage(error.player_error_message),
player_error_context: translateContext(error.player_error_context)
};
}
// player is the instance of THEOplayer.Player
initTHEOplayerMux(player, {
debug: false,
errorTranslator,
data: {
env_key: "ENV_KEY",
// ...
}
});
If you return false
from your errorTranslator
function then the error will not be tracked. Do this for non-fatal errors that you want to ignore. If your errorTranslator
function itself raises an error, then it will be silenced and the player's original error will be used.
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.
// player is the instance of THEOplayer.Player
initTHEOplayerMux(player, {
debug: false,
automaticErrorTracking: false,
data: {
env_key: "ENV_KEY",
// ...
}
});
@mux/mux-data-theoplayer
Mux has been tested with and supports THEOplayer's Ads integration. Simply configure the ads as you would with THEOplayer normally, and Mux will track ads automatically. No additional configuration is needed.
Other THEOplayer ad integrations, such as Google IMA, may work out of the box but have not currently been tested. Please contact us with any questions.
If you have integrated a custom domain for Data collection, specify your custom domain by setting beaconCollectionDomain
.
// player is the instance of THEOplayer.Player
initTHEOplayerMux(player, {
debug: false,
beaconCollectionDomain: 'CUSTOM_DOMAIN', // ex: 'foo.bar.com'
data: {
env_key: "ENV_KEY",
// ...
}
});
In some cases, you may want to stop tracking an instance of THEOplayer. To this, we provide a destroy
method within the returned object of initTHEOplayerMux
, which will immediately end the active Mux Data view and stop tracking the THEOplayer instance.
// player is the instance of THEOplayer.Player
let monitor = initTHEOplayerMux(player, {
debug: false,
data: {
env_key: "ENV_KEY",
// ...
}
});
// once ready to destroy the monitor
monitor.destroy();
mux-embed
to v5.4.3mux-embed
to v5.4.2mux-embed
to v5.4.1Add updateData function that allows Mux Data metadata to be updated mid-view.
Update mux-embed
to v5.4.0
mux-embed
to v5.3.3mux-embed
to v5.3.2mux-embed
to v5.3.1mux-embed
to v5.3.0mux-embed
to v5.2.1mux-embed
to v5.2.0Target ES5 for bundles and validate bundles are ES5
Update mux-embed
to v5.1.0
mux-embed
to v5.0.0mux-embed
to v4.30.0mux-embed
to v4.29.0mux-embed
to v4.28.1use a new mechanism to track rebuffering for better accuracy
Update mux-embed
to v4.28.0
fix an issue where seek latency could be unexpectedly large
fix an issue where seek latency does not include time at end of a view
Update mux-embed
to v4.27.0
mux-embed
to v4.26.0mux-embed
to v4.25.1mux-embed
to v4.25.0Fix an issue where beacons over a certain size could get hung and not be sent
Update mux-embed
to v4.24.0
Fix an issue where tracking rebuffering can get into an infinite loop
Update mux-embed
to v4.23.0
mux-embed
to v4.22.0mux-embed
to v4.21.0mux-embed
to v4.20.0mux-embed
to v4.19.0mux-embed
to v4.18.0Support player_error_context
in errorTranslator
Update mux-embed
to v4.17.0
Adds support for new and updated fields: renditionchange
, error, DRM type, dropped frames, and new custom fields
Update mux-embed
to v4.16.0
Expose utils
on SDK initialization function to expose utils.now()
for player_init_time
Record request_url
and request_id
with network events
Update mux-embed
to v4.15.0
mux-embed
to v4.14.0mux-embed
to v4.13.4mux-embed
to v4.13.3mux-embed
to v4.13.2mux-embed
to v4.13.1Upgraded internal webpack version
Update mux-embed
to v4.13.0
mux-embed
to v4.12.1mux-embed
to v4.12.0mux-embed
to v4.11.0mux-embed
to v4.10.0mux-embed
to v4.9.4mux-embed
to v4.9.3mux-embed
to v4.9.2mux-embed
to v4.9.1mux-embed
to v4.9.0mux-embed
to v4.8.0mux-embed
to v4.7.0Introducing HLS Session Data support
Update mux-embed
to v4.6.2
mux-embed
to v4.6.1requestcompleted
event for every manifest requestprogramchange
may not have been tracked correctlydestroy
was called multiple times, it would raise an exceptionplayer_remote_played
may not be tracked correctlyrenditionchange
tracking eventmux-embed
to 3.0.0