- Introduction to Data
- Track your video performance
- HTML5 video element
- HLS.js
- AVPlayer
- ExoPlayer
- Dash.js
- Video.js
- React native video
- Kaltura (android)
- Kaltura (iOS)
- Kaltura (web)
- JW Player (web)
- JW Player (iOS)
- Android MediaPlayer
- Bitmovin player
- Akamai media player
- NexPlayer
- Ooyala player
- Shaka player
- Azure media player
- THEOplayer (web)
- THEOplayer (iOS)
- Flowplayer
- Brightcove (web)
- Brightcove (iOS)
- Brightcove (android)
- CTS PDK
- Chromecast
- Roku
- Samsung (Tizen)
- LG
- Agnoplay player
- Make API requests
- Setup alerts
- Make your data actionable with metadata
- Track autoplaying videos
- Extend Data with custom metadata
- Track CDN for request metrics
- See how many people are watching
- Build a custom integration
- Understand metric definitions
- Export raw video view data
- Ensure privacy compliance
- Mux Data FAQs
Monitor JW Player
This guide walks through integration with JW Player for the web to collect video performance metrics with Mux data.
In this guide:
1
Install jwplayer-mux
1
Install jwplayer-mux
Install jwplayer-mux
from our CDN.
2
Initialize Mux Data
2
Initialize Mux Data
Attach JW player instance to the jwplayer-mux
montior.
3
Make your data actionable
3
Make your data actionable
Use metadata fields to make the data collected by Mux actionable and useful.
4
Changing the video
4
Changing the video
If your implementation changes the video without changing the video player, let mux know to start tracking a new view.
5
Advanced options
5
Advanced options
Depending on the details of your implementation, you may want to leverage some of the advanced options of jwplayer-mux.
Release Notes
Release Notes
Include the Mux JavaScript SDK on every page of your web app that includes video.
<!-- Include jwplayer-mux after the core JW Player javascript file --> <!-- Note that the KEY in the example should be replaced with the key provided by JW Player for your account. --> <script src="https://content.jwplatform.com/libraries/KEY.js"></script> <script src="https://src.litix.io/jwplayer/4/jwplayer-mux.js"></script>
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 jwplayer
like you normally would and get the return value (a reference to the player
). Call initJWPlayerMux
with the player reference and the SDK options.
<div id="my-player"></div> <script> const conf = { // Insert JW Player configuration here }; const playerInitTime = Date.now(); const player = jwplayer('my-player').setup(conf); // Initialize Mux Data monitoring initJWPlayerMux(player, { debug: false, data: { env_key: 'EXAMPLE_ENV_KEY', // required // Metadata player_name: '', // ex: 'My Main Player' player_init_time: playerInitTime // ex: 1451606400000 // ... and other metadata } }); </script>
Be sure to call initJWPlayerMux
immediately after initializing JW player so that Mux can attach as soon as possible.
The only required field in the options
that you pass into jwplayer-mux
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.
initJWPlayerMux(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 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).
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).
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
See metadata in Make your data actionable for the full 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_
.
It's best to change the video info immediately after telling the player which new source to play.
// player is the instance returned by the `jwplayer` function player.mux.emit('videochange', { video_id: 'abc345', video_title: 'My Other Great Video', video_series: 'Weekly Great Videos', // ... });
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. 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 returned by the `jwplayer` function player.mux.emit('programchange', { video_id: 'abc345', video_title: 'My Other Great Video', video_series: 'Weekly Great Videos', // ... });
Disable cookies
By default, Mux plugins for HTML5-based players use a cookie to track playback across subsequent page views. 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.
This is done by setting disableCookies: true
in the options passed to the Mux plugin.
initJWPlayerMux(player, { debug: false, disableCookies: true, data: { env_key: "ENV_KEY", // ... });
Over-ride 'do not track' behavior
By default, jwplayer-mux
does 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
.
initJWPlayerMux(player, { debug: false, respectDoNotTrack: true, data: { env_key: "ENV_KEY", // ... });
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, jwplayer-mux
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 returned by the `jwplayer` function player.mux.emit('error', { player_error_code: 100, player_error_message: 'Description of 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 detailed 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
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.
function errorTranslator (error) { return { player_error_code: translateCode(error.player_error_code), player_error_message: translateMessage(error.player_error_message), }; } initJWPlayerMux(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.
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.
initJWPlayerMux(player, { debug: false, automaticErrorTracking: false, data: { env_key: "ENV_KEY", // ... } });
Ads tracking with jwplayer-mux
Mux supports JW Player's VAST integration for pre-, mid-, and post-roll ads. Simply configure these plugins as you would normally, and Mux will track ads automatically. No additional configuration is needed.
Other JW Player ad integrations, such as Google IMA and FreeWheel have not been tested, but may work out of the box. Please contact us with any questions.
Current release
v4.3.1
- Remove unneeded debug logging
Previous releases
v4.3.0
- Update
mux-embed
to v4.2.0 - Fix an issue where views that resulted from
programchange
may not have been tracked correctly - Fix an issue where if
destroy
was called multiple times, it would raise an exception
v4.2.0
- Update
mux-embed
to v4.1.1 - Fix an issue where
player_remote_played
would not be reported correctly
v4.1.0
- Improve metrics by sending the
playing
andadplaying
events at more appropriate times
v4.0.0
- Update mux-embed to v4.0.0
- Support server-side device detection
v3.1.0
- add rendition change event for getting bitrate metrics
v3.0.0
- bump
mux-embed
dependency to3.0.0