```
### Over-ride 'do not track' behavior
By default, `cts-mux` does not respect [Do Not Track](https://www.eff.org/issues/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`.
```html
```
### Customize error tracking behavior
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.
There is currently no way to change the default error tracking behavior. If this is something you need in your CTS PDK integration, please reach out.
### Ads tracking with `cts-mux`
Mux has been tested with CTS's VAST plugin for ad support. Configure the VAST plugin as you would with your PDK player normally, and Mux will track ads automatically. No additional configuration is needed.
# Monitor Chromecast
This guide walks through integration with Chromecast to collect video performance metrics with Mux data.
Mux Data is the best way to monitor video streaming performance.
Integration is easy - just initialize the Mux SDK, pass in some metadata, and you're up and running in minutes.
This documents integration instructions for Chromecast. For other players, see the additional Integration Guides.
## Features
The following data can be collected by the Mux Data SDK when you use the \{featureDef.name} SDK, as described
below.
```md
- Engagement metrics
- Quality of Experience Metrics
- Web metrics such as Player Startup Time, Page Load Time, etc
- Average Bitrate metrics and `renditionchange` events
- Request metrics
- Customizable Error Tracking
- Custom Beacon Domain
```
Notes:
```md
Average Bitrate metrics available in v4.2.11 and newer.
```
## 1. Include the Mux Data SDK
Mux supports Chromecast applications that are built on top of the Cast Application Framework [CAF](https://developers.google.com/cast/docs/caf_receiver_overview) Receiver SDK. The CAF Receiver SDK supports the following [streaming protocols](https://developers.google.com/cast/docs/media#delivery-methods-and-adaptive-streaming-protocols).
A Chromecast application contains two main components: a sender and a receiver. The Mux Data SDK is integrated at the receiver side; include the `chromecast-mux.js` JavaScript file within your custom receiver application. You can use the Mux-hosted version of the script to receive automatic updates. (The API will not change within major versions, as in `chromecast/MAJOR_VERSION/chromecast-mux.js`).
```npm
npm install --save @mux/mux-data-chromecast
```
```yarn
yarn add @mux/mux-data-chromecast
```
```cdn
```
## 2. Initialize Mux Data
Get your `ENV_KEY` from the [Mux environments dashboard](https://dashboard.mux.com/environments).
`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.
To monitor video playback within your Chromecast application, pass the `PlayerManager` instance to `initChromecastMux` along with SDK options and metadata.
You can initialize within a message interceptor for the `LOAD` event, or immediately on app load as before. This suggestion changed in version 4.0.0 and newer.
```js
import initChromecastMux from '@mux/mux-data-chromecast';
var app = {
init: function () {
const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
let firstPlay = true;
let playerInitTime = initChromecastMux.utils.now();
playerManager.setMessageInterceptor(cast.framework.messages.MessageType.LOAD, loadRequestData => {
if (firstPlay) {
initChromecastMux(playerManager, {
debug: false,
data : {
env_key: 'ENV_KEY', // required
// Metadata
player_name: 'Custom Player', // ex: 'My Main Player'
player_init_time: playerInitTime,
// ... additional metadata
}
});
}
return loadRequestData;
});
context.start();
}
};
$(document).ready(function () {
app.init();
});
```
After you've finished integration, the quickest way to see that the SDK is loaded is to pass `debug: true` in the options passed to the SDK. With this flag enabled, you can open the debug console, and you should start seeing debug statements from \[mux] when you click play on the video.
After playing a video, a few minutes after you stop watching, you'll see the results in your Mux account. We'll also email you when your first video view has been recorded. Log in to the dashboard and find the environment that corresponds to your env\_key and look for video views.
Note that it may take a few minutes for views to show up in the Mux Data dashboard.
## 3. Make your data actionable
[Detailed Documentation](/docs/guides/make-your-data-actionable-with-metadata)
Options are provided via the `data` object passed in the call to `initChromecastMux`.
All metadata details except for `env_key` are optional, however you'll be able to compare and see more interesting results as you include more details. This gives you more metrics and metadata about video streaming, and allows you to search and filter on important fields like the player version, CDN, and video title.
For more information, see the [Metadata Guide](/docs/guides/make-your-data-actionable-with-metadata).
## 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 `initChromecastMux`. Then, once you have the metadata, you can update the metadata with the `updateData` method.
```js
playerManager.mux.updateData({ video_title: 'My Updated Great Video' });
```
## 5. Changing the video
There are two cases where the underlying tracking of the video view need 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 (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
In order 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. See metadata in [Make your data actionable](/docs/guides/make-your-data-actionable-with-metadata) 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.
The source change should be done by intercepting the `cast.framework.messages.MessageType.LOAD` message and doing the following:
```js
playerManager.setMessageInterceptor(cast.framework.messages.MessageType.LOAD, loadRequestData => {
// It's important to only call this on subsequent videos being loaded, not
// the first playback (where you call `initChromecastMux`).
if (!firstVideo) {
playerManager.mux.emit('videochange', { ... });
}
return loadRequestData;
});
```
### 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](/docs/guides/make-your-data-actionable-with-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.
## 6. Advanced options
### Customize error tracking behavior
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-chromecast` 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.
```js
playerManager.mux.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](https://developer.mozilla.org/en-US/docs/Web/API/MediaError), 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.*
### 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.
```js
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)
};
}
initChromecastMux(playerManager, {
debug: false,
errorTranslator: errorTranslator,
data : {
env_key: 'ENV_KEY', // required
// Metadata
player_name: 'Custom Player', // ex: 'My Main Player'
// ... additional metadata
}
});
```
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.
```js
initChromecastMux(playerManager, {
debug: false,
automaticErrorTracking: false,
data : {
env_key: 'ENV_KEY', // required
// Metadata
player_name: 'Custom Player', // ex: 'My Main Player'
// ... additional metadata
}
});
```
### Customize beacon collection domain
If you have [integrated a custom domain for Data collection](/docs/guides/integrate-a-data-custom-domain), specify your custom domain by setting `beaconCollectionDomain`.
```js
initChromecastMux(playerManager, {
debug: false,
beaconCollectionDomain: 'CUSTOM_DOMAIN', // ex: 'foo.bar.com'
data: {
env_key: "ENV_KEY",
// ...
}
});
```
## Destroying the Monitor
There are certain use cases where you want to stop monitoring playback within a player (for instance if the player is no longer being used, you are recycling players, or you are shutting down the application). In this case, you should make sure to destroy the monitor. This can be done by simply calling `playerManager.mux.destroy()`.
# Monitor Roku
This guide walks through integration with Roku to collect video performance metrics with Mux data.
Mux's Roku integration supports Roku SceneGraph applications, in conjunction with standard `Video` nodes. Mux runs as a `Task` alongside the `Video` node, and supports instances where the `Video` nodes are reused with additional content as well as when the `Video` nodes are reset between content.
## Features
The following data can be collected by the Mux Data SDK when you use the \{featureDef.name} SDK, as described
below.
```md
- Engagement metrics
- Quality of Experience Metrics
- Custom Dimensions
```
Notes:
```md
Video Quality metrics are not available.
```
## 1. Include the Mux Data SDK
Place the SDK file in your `libs` folder. The latest version of the SDK can be found here:
```sh
https://src.litix.io/roku/2/mux-analytics.brs
```
## 2. Setup a new Mux Task
Create a new `Task` XML named `MuxTask.xml` inside your `components` folder and give it the following interface. This is used to link the `mux-analytics.brs` file into your application.
```html
```
## 3. Setup the task to respond to video events
Within your main application, create the Mux Task node, and pass the `Video` node that you are tracking to it. This should be done before the content is set into the `Video` node so that Mux can track the load process.
Get your `ENV_KEY` from the [Mux environments dashboard](https://dashboard.mux.com/environments).
`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.
```js
m.mux = m.top.CreateNode("mux")
m.mux.setField("video", m.video)
muxConfig = {
env_key: "ENV_KEY",
}
m.mux.setField("config", muxConfig)
m.mux.control = "RUN"
' Load the video into the Video node
```
After you've integrated, start playing a video in the player you've integrated with. A few minutes after you stop watching, you'll see the results in your Mux account. We'll also email you when your first video view has been recorded.
You can also test that Mux is receiving data in the Mux Data dashboard. Login to the dashboard and find the environment that corresponds to your `ENV_KEY` and look for video views.
Note that it may take a few minutes for views to show up in the Mux Data dashboard.
## 4. Debugging
To help you with the integration process and ensure you have successfully incorporated the SDK within your player, we have provided a number of optional manifest attributes. These attributes can help you better understand how the MUX SDK event tracking works as well as show you the actual data being collected. Some of the benefits of using some of the debugging attributes (mentioned below) are that you will be able to see the SDK events and data collected as it occurs.
**NOTE:** The outputs illustrated below are printed on a single line within the terminal to reduce clutter.
Note that the following settings are configured in your application's `manifest` file, rather than passed into the config object.
### mux\_debug\_events
#### Values
`full`, `partial` or `none`
#### Description
Outputs the event at the time it occurs. Default value is `none`
#### Example output
Property set to `partial`:
```sh
[mux-analytics] EVENT playerready
```
Property set to `full`:
```sh
[mux-analytics] EVENT playing
{
viewer_application_name:Roku,
mux_api_version:2.1,
view_seek_duration:0,
viewer_application_version:9.20,
player_name:Reset Player,
viewer_time:1582317809984,
view_start:1582317808627,
player_model_number:4660X,
video_source_mime_type:mp4,
event:playing,
...
```
***
### mux\_debug\_beacons
#### Values
`full`, `partial` or `none`
#### Description
Outputs the data (full) or event(s) (partial) that is being sent (at the time of sending). Default value is `none`.
#### Example output
Property set to `partial`:
```sh
[mux-analytics] BEACON (2) [ playerready viewstart ]
```
Property set to `full`:
```sh
[mux-analytics] BEACON (2)
[
{
viewer_application_name:Roku,
mux_api_version:2.1,
view_seek_duration:0,
viewer_application_version:9.20,
player_name:Reset Player,
viewer_time:1582317809984,
view_start:1582317808627,
player_model_number:4660X,
video_source_mime_type:mp4,
event:playerready,
...
}, {
viewer_application_name:Roku,
mux_api_version:2.1,
view_seek_duration:0,
viewer_application_version:9.20,
player_name:Reset Player,
viewer_time:1582317809984,
view_start:1582317808627,
player_model_number:4660X,
video_source_mime_type:mp4,
event:viewstart,
...
}
]
```
***
### `mux_base_url`
#### Values
Protocol + domain name. Eg. `https://img.litix.io`
#### Description
Controls to which domain the data should be sent. Useful for environmental builds of your project
## 5. Make your data actionable
The Roku SDK supports adding metadata via two different mechanisms.
The majority of the metadata should be passed inside the `muxConfig` object that is passed to the Mux Task. You can read detailed information about the fields that are supported in [Metadata](/docs/guides/make-your-data-actionable-with-metadata). To update any field, update this within `muxConfig` and then call `m.mux.setField("config", muxConfig)`.
Some other underlying information is mapped from standard [Roku content metadata](https://developer.roku.com/docs/developer-program/getting-started/architecture/content-metadata.md), most of which you probably already set when creating your video. In particular, the metadata fields that you should set (if you do not already) are:
* *ContentType*
* *URL*
* *Live*
* *StreamFormat*
* *Length*
## 6. Advertising configuration
If advertising is to be used, you must send the appropriate events to the Mux Task, as shown below.
```js
function setUpRokuAdFramework
adIface.SetTrackingCallback(adTrackingCallback, adIface)
end function
function adTrackingCallback(obj = Invalid as Dynamic, eventType = Invalid as Dynamic, ctx = Invalid as Dynamic)
m.mux = GetGlobalAA().global.findNode("mux")
adUrl = Invalid
if obj <> Invalid
adUrl = obj.getAdUrl()
end if
m.mux.setField("rafEvent", {obj: { adurl: adUrl }, eventType:eventType, ctx:ctx})
end function
```
If you would like to pass your own ad parameters, you can do so by setting `ctx.mux` to an associative array with the values you desire. Currently the only value supported is `ad_type`.
```js
function adTrackingCallback(obj = Invalid as Dynamic, eventType = Invalid as Dynamic, ctx = Invalid as Dynamic)
m.mux = GetGlobalAA().global.findNode("mux")
adUrl = Invalid
if obj <> Invalid
adUrl = obj.getAdUrl()
end if
# Add your ad_type if you desire
ctx.mux = {}
ctx.mux.ad_type = "preroll"
m.mux.setField("rafEvent", {obj: { adurl: adUrl }, eventType:eventType, ctx:ctx})
end function
```
If you are utilizing RAF's `renderStitchedStream` method to stitch ads and content together client-side, then you must tell the Mux SDK that this is in use. This is set via `useRenderStitchedStream` on the Mux Task, set to `true`, such as:
```js
mux.setField("useRenderStitchedStream", true)
```
If you are *not* utilizing `renderStitchedStream` but instead controlling ad and content playback directly, then you need to set `useRenderStitchedStream` to `false`.
If you are utilizing server-side ad insertion (SSAI), you should signal that to the SDK by setting `useSSAI` to `true`:
```js
mux.setField("useSSAI", true)
```
## 7. Additional configuration
There are a number of options you can configure on MuxTask, which can be used to customize the SDK:
| Field Name | Type | Description |
|:-|:-|:-|
| `video` | `Node` | The `Video` node that is being tracked. |
| `config` | `assocarray` | Configuration for the Mux task, including env key and additional metadata. |
| `rafEvent` | `assocarray` | Used to forward RAF events from your application into the Mux SDK. See [Advertising Configuration](#6-advertising-configuration) for more information. |
| `view` | `String` | Used to control when views start and end directly. See [Controlling View Start and End Directly](#controlling-view-start-and-end-directly) for more information. |
| `disableAutomaticErrorTracking` | `Boolean` | Used to signal errors manually. See [Manually Tracking Errors](#manually-tracking-errors) for more information. |
| `error` | `assocarray` | Used to signal errors manually. See [Manually Tracking Errors](#manually-tracking-errors) for more information. |
| `exit` | `Boolean` | Used to exit tracking directly. See [Controlling View Start and End Directly](#controlling-view-start-and-end-directly) for more information. |
| `exitType` | `String` | Used to control the mechanism used while exiting tracking. See [Controlling View Start and End Directly](#controlling-view-start-and-end-directly) for more information. |
| `useRenderStitchedStream` | `Boolean` | Used to set whether `renderStitchedStream` is used for advertising in your application. See [Advertising Configuration](#6-advertising-configuration) for more information. |
| `useSSAI` | `Boolean` | Used to set whether Roku's built-in server-side-ad-insertion is used for advertising in your application. See [Advertising Configuration](#6-advertising-configuration) for more information. |
| `randomMuxViewerId` | `Boolean` | Used to instruct Mux to use a random viewer ID instead of an ID based on the device. By default, Mux utilizes the [device RIDA](https://developer.roku.com/docs/references/brightscript/interfaces/ifdeviceinfo.md#getrida-as-string) as the viewer ID. If this flag is enabled, unique viewer counts may be inflated. |
| `cdn` | `String` | Used to manually signal when the CDN changes. See [CDN Tracking](#cdn-tracking) for more information. |
| `disablePlayheadRebufferTracking` | `Boolean` | Used to control rebuffering directly. See [Rebuffer Controls](#rebuffer-controls) for more information. |
| `rebufferstart` | `Boolean` | Used to control rebuffering directly. See [Rebuffer Controls](#rebuffer-controls) for more information. |
| `rebufferend` | `Boolean` | Used to control rebuffering directly. See [Rebuffer Controls](#rebuffer-controls) for more information. |
| `disableDecoderStats` | `Boolean` | By default, Mux sets `enableDecoderStats` to true on the `Video` node. Set this to `true` not enable decoder stats; dropped frames will no longer be tracked. |
| `playback_mode` | `assocarray` | Used to set and update [Playback Mode](#playback-mode). |
| `request` | `assocarray` | Used to trigger [custom network request events](#network-custom-request-event). |
### Controlling View Start and End Directly
In some situations, it is necessary to directly signal the beginning or ending of a `view` to Mux. This is necessary when the `Video` Node is recycled (i.e. more pieces of content are loaded into the same Node), or when using advertising, as the ads run outside of the lifecycle of the Video.
Note: A `view` is defined as the user watching a single piece of *content*, which includes any advertising.
```js
mux = GetGlobalAA().global.findNode("mux")
' To signal the start of a view:
mux.setField("view", "start")
' To signal the end of a view:
mux.setField("view", "end")
```
The `exitType` setting controls the behavior of the task when a request to exit/terminate the thread is invoked (via `mux.exit=true`). The default value of `exitType` is `hard`.
If the value is set to `hard` then the thread terminates immediately and any data that has not propagated already to the MUX servers is lost.
If the value is set to `soft` then the thread sends all the remaining data to the MUX servers and terminates afterward.
To change value to `soft` call `m.mux.setField("exitType", "soft")`
NOTE: This means that there might be a time difference between you calling `mux.exit=true` and the task thread actually terminating. Please ensure you have a single `MUX Task` running at any given time.
### Manually Tracking Errors
The Mux SDK for Roku tracks error events from the Video node automatically, and reports them as fatal playback errors. If you would like to disable this automatic error tracking, you can set the following in your MuxTask.xml:
```js
```
While it is not advised to control this at runtime, you can also set this by calling
```js
mux.setField("disableAutomaticErrorTracking", true)
```
In order to emit events, you will need to trigger any errors directly, by calling
```js
mux.setField("error", {
player_error_code: errorCode,
player_error_message: errorMessage,
player_error_context: errorContext,
player_error_severity: errorSeverity,
player_error_business_exception: isBusinessException
})
```
The error code and message should always be provided, and you can set the other fields if desired. The possible values or `errorSeverity` are `"warning"` or `"fatal"`. Read more about [Error Classification](/docs/guides/error-categorization) for more details.
### CDN Tracking
The Mux SDK for Roku can listen to CDN change events. In order to emit events, you will need to trigger any CDN changes directly, by calling
```js
' The "new_cdn" string should be the new CDN name
mux.setField("cdn", "new_cdn")
```
### Rebuffer Controls
Mux does not suggest disabling the automatic rebuffer tracking. The following is for advanced usage only.
The Mux SDK for Roku tracks error events from the Video node automatically. If you would like to disable this automatic rebuffer tracking, you can set the following in your MuxTask.xml:
```js
```
While it is not advised to control this at runtime, you can also set this by calling
```js
mux.setField("disablePlayheadRebufferTracking", true)
```
Rebuffer start and end events can be emitted by calling the following
```js
mux.setField("rebufferstart", true)
```
```js
mux.setField("rebufferend", true)
```
### Playback Mode
A playback mode event can be emitted by calling the following
```js
mux.setField("playback_mode", {
player_playback_mode: mode,
player_playback_mode_data: data
})
```
The `mode` should always be provided, suggested values are: `inline`, `fullscreen`, `mini` and `pip`.
The `data` is optional, if provided it should be a parse-able JSON string.
A `playbackmodechange` event will be emitted containing the following fields:
* `player_playback_mode` (containing the mode set)
* `player_playback_mode_data` (containing the data set)
* `ad_playing_time_ms_cumulative` (containing ad watch time)
* `view_playing_time_ms_cumulative` (containing the total content watch time plus ad watch time)
### Network custom request event
Custom request events can be emitted with custom data for network requests by calling the following
```js
mux.setField("request", manifestRequest)
```
The `manifestRequest` must be a parse-able JSON string.
The following fields can be included in `manifestRequest`. All fields should be numeric values, not strings, except where noted:
* `type` (required, string) - The status of the request: `completed`, `failed`, or `canceled`
* `request_start` (numeric) - Timestamp in milliseconds since the Unix epoch when the request was initiated
* `request_response_start` (numeric) - Timestamp in milliseconds since the Unix epoch when the first byte of the response was received
* `request_response_end` (numeric) - Timestamp in milliseconds since the Unix epoch when the last byte of the response was received
* `request_bytes_loaded` (numeric) - The total number of bytes loaded as part of this request
* `request_hostname` (string) - The hostname portion of the URL that was requested
* `request_type` (string) - The type of content being requested. One of: `manifest`, `video`, `audio`, `video_init`, `audio_init`, `media`, `subtitle`, or `encryption`
* `request_id` (string) - A unique identifier for the request
* `request_url` (string) - The URL that was requested
* `request_labeled_bitrate` (numeric) - Labeled bitrate in bps of the video, audio, or media segment that was downloaded
* `request_response_headers` (object) - A map of response headers and their values
* `request_media_duration` (numeric) - The duration of the media loaded, in seconds. Should not be included for manifest requests
* `request_video_width` (numeric) - For events with `media` or `video` `request_type`, the width of the video included in the segment/fragment
* `request_video_height` (numeric) - For events with `media` or `video` `request_type`, the height of the video included in the segment/fragment
* `request_error` (string) - The name of the error event that occurred (e.g., `FragLoadError`)
* `request_error_code` (numeric) - The response code of the request that spawned the error (e.g., 401, 400, 500)
* `request_error_text` (string) - The message returned with the failed status code
Depending on the `type` value, a corresponding event will be emitted: `requestcompleted` (for `type: "completed"`), `requestfailed` (for `type: "failed"`), or `requestcanceled` (for `type: "canceled"`).
For more information about these fields, see [Network Request Data](/docs/guides/mux-data-playback-events#network-request-data).
#### Latency and Throughput Calculation
If you set `request_start`, `request_response_start`, `request_response_end`, and `request_bytes_loaded`, latency and throughput will be automatically calculated and sent in each event.
* Latency is calculated as the time between `request_start` and `request_response_start`.
* Throughput is calculated as `request_bytes_loaded` divided by the time between `request_response_start` and `request_response_end`.
#### Request Duration Calculation
If the request is completed (`type` is `"completed"`), the `request_type` is `"api"` or `"encryption"`, and both `request_start` and `request_response_end` are present as valid numeric values, the total request duration (`request_duration`) will be calculated as `request_response_end - request_start` and included in the event. Requests of type `"api"` or `"encryption"` are limited to a maximum of 5 per view; if this limit is exceeded, the event is discarded and not sent to Mux.
# Samsung-Tizen
This guide walks through integration with Samsung Tizen to collect video performance metrics with Mux data.
Mux Data is the best way to monitor video streaming performance.
Integration is easy - just initialize the Mux SDK, pass in some metadata, and you're up and running in minutes.
This documents integration instructions for Samsung Tizen TVs. For other players, see the additional Integration Guides.
## Features
The following data can be collected by the Mux Data SDK when you use the \{featureDef.name} SDK, as described
below.
```md
- Engagement metrics
- Quality of Experience Metrics
- Custom Beacon Domain
```
Notes:
```md
No notes provided
```
## 1. Include the Mux Data SDK
Mux Data supports applications built for Samsung Tizen TVs using JavaScript and Tizen's [AVPlay API](https://developer.samsung.com/tv/develop/api-references/samsung-product-api-references/avplay-api). The Samsung Tizen Smart TV SDK supports C++, JavaScript, and Microsoft .NET; this SDK is only compatible with JavaScript applications using AVPlay.
Include the Mux Data SDK by including the `tizen-mux.js` JavaScript file within your `index.html` file defining your application. You can use the Mux-hosted version of the script to receive automatic updates. (The API will not change within major versions, as in `tizen/MAJOR_VERSION/tizen-mux.js`.)
```html
```
## 2. Initialize Mux Data
To monitor video playback within your Tizen application, pass the AVPlay player instance to `monitorTizenPlayer` along with SDK options and metadata.
```js
// Place in your application initialization code, around
// where you call `prepare`
var player = $('#my-player').get(0);
player.url = this.url;
var playerInitTime = monitorTizenPlayer.utils.now();
this.prepare();
monitorTizenPlayer(player, {
debug: true,
data: {
env_key: 'ENV_KEY', // required
// Metadata
player_name: 'Custom Player', // ex: 'My Main Player'
player_init_time: playerInitTime,
// ... additional metadata
},
// Optional passthrough listener
playbackListener: playbackListener
});
```
Tizen's AVPlay API does not allow multiple AVPlayPlaybackCallback listeners to be registered to a player. If you require your own listener to be registered, you must pass this in as `playbackListener` as shown above. Mux's SDK will proxy the calls to your listener. (Note: the location of this changed with v1.0.0)
To stop monitoring your player (e.g. when playback is complete), call `player.mux.stopMonitor()`.
Log in to the Mux dashboard and find the environment that corresponds to your `env_key` and look for video views. It takes about a minute or two from tracking a view for it to show up on the Metrics tab.
**If you aren't seeing data**, check to see if you have an ad blocker, tracking blocker or some kind of network firewall that prevents your player from sending requests to Mux Data servers.
## 3. Make your data actionable
[Detailed Documentation](/docs/guides/make-your-data-actionable-with-metadata)
Options are provided via the data object passed in the call to `monitorTizenPlayer`.
All metadata details except for `env_key` are optional, however you'll be able to compare and see more interesting results as you include more details. This gives you more metrics and metadata about video streaming, and allows you to search and filter on important fields like the player version, CDN, and video title.
```js
monitorTizenPlayer(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, see the [Metadata Guide](/docs/guides/make-your-data-actionable-with-metadata).
## 4. Advanced options
### Customize beacon collection domain
If you have [integrated a custom domain for Data collection](/docs/guides/integrate-a-data-custom-domain), specify your custom domain by setting `beaconCollectionDomain`.
```js
monitorTizenPlayer(player, {
debug: false,
beaconCollectionDomain: 'CUSTOM_DOMAIN', //ex: 'foo.bar.com'
data: {
env_key: 'ENV_KEY', // required
// ,,,
}
});
```
# Monitor LG
This guide walks through integration with LG Smart TVs to collect video performance metrics with Mux data.
## Features
The following data can be collected by the Mux Data SDK when you use the \{featureDef.name} SDK, as described
below.
```md
- Engagement metrics
- Quality of Experience Metrics
```
Notes:
```md
No notes provided
```
## 1. Integration overview
LG Smart TV applications are built on top of the HTML5 video technology. To support video streaming, these applications can be integrated with player SDKs such as the [HLS.js](https://video-dev.github.io/hls.js/) and [Dash.js](https://github.com/Dash-Industry-Forum/dash.js).
Due to the HTML5 nature of LG Smart TV applications, the Mux Data integration with LG televisions uses one of the HTML5 integrations, such as the ones listed above. When setting up your application, you should check which video player engine that is used, and depending on that, utilize the appropriate integration point within `mux-embed`.
Check these 3 web integration guides for more details:
* [HTML5 video element](/docs/guides/monitor-html5-video-element)
* [HLS.js](/docs/guides/monitor-hls-js)
* [Dash.js](/docs/guides/monitor-dash-js)
Get your `ENV_KEY` from the [Mux environments dashboard](https://dashboard.mux.com/environments).
`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.
```js
// main.js
play: function() {
var data = {
env_key: 'ENV_KEY', // required
player_name: 'My Custom Player',
player_init_time: mux.utils.now(),
// ... additional metadata
};
switch (this.playerEngine) {
case this.PLAYENGINE_HLSJS:
if (Hls.isSupported()) {
const hls = new Hls();
hls.loadSource('');
hls.attachMedia(this.player);
hls.on(Hls.Events.MANIFEST_PARSED,function(e,d) {
app.player.play();
});
mux.monitor('#my-player', {
debug: true,
hlsjs: hls,
Hls: Hls,
data: data
});
this.hls = hls;
}
break;
case this.PLAYENGINE_DASHJS:
const dashjsPlayer = dashjs.MediaPlayer().create();
dashjsPlayer.getDebug().setLogToBrowserConsole(false);
mux.monitor('#my-player', {
debug: true,
dashjs: dashjsPlayer,
data: data
});
dashjsPlayer.initialize(this.player, 'http://dash.edgesuite.net/envivio/EnvivioDash3/manifest.mpd', true);
this.dashjsPlayer = dashjsPlayer;
break;
}
}
```
After you've finished integration, the quickest way to see that the SDK is loaded is to pass `debug: true` in the options passed to the SDK. With this flag enabled, you can open the debug console, and you should start seeing debug statements from \[mux] when you click play on the video.
After playing a video, a few minutes after you stop watching, you'll see the results in your Mux account. We'll also email you when your first video view has been recorded. Log in to the dashboard and find the environment that corresponds to your env\_key and look for video views.
Note that it may take a few minutes for views to show up in the Mux Data dashboard.
## 2. Make your data actionable
Options are provided via the data object passed in the call to `mux.monitor`.
All metadata details except for `env_key` are optional, however you'll be able to compare and see more interesting results as you include more details. This gives you more metrics and metadata about video streaming, and allows you to search and filter on important fields like the player version, CDN, and video title.
```js
mux.monitor('#my-player', {
debug: false,
hlsjs: hls,
Hls,
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, see the [Metadata Guide](/docs/guides/make-your-data-actionable-with-metadata).
## 3. Advanced options
### Customize beacon collection domain
If you have [integrated a custom domain for Data collection](/docs/guides/integrate-a-data-custom-domain), specify your custom domain by setting `beaconCollectionDomain`.
```js
mux.monitor('#my-player', {
debug: false,
beaconCollectionDomain: 'CUSTOM_DOMAIN', // ex: 'foo.bar.com'
hlsjs: hls,
Hls,
data: {
env_key: 'ENV_KEY', // required
// ... additional metadata
}
});
```
# Monitor Agnoplay player service
This guide walks through integration with Agnoplay to collect video performance metrics with Mux Data. Because Agnoplay has Mux Data fully pre-integrated there will be no need of any development effort to activate Mux Data.
This integration is managed and operated by [Agnoplay](https://agnoplay.com).
Feedback should be made through your Agnoplay representative [https://agnoplay.com](https://agnoplay.com) or info@agnoplay.com.
# Environment key
Get your `ENV_KEY` from the [Mux environments dashboard](https://dashboard.mux.com/environments).
`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.
# Contact Agnoplay
Contact your Agnoplay representative through [https://agnoplay.com](https://agnoplay.com) or [info@agnoplay.com](mailto:info@agnoplay.com), and provide them with your environment key.
# Wait for the magic
The Agnoplay support team will add your environment key to the configuration of Agnoplay instance, after which your Mux Data environment will be populated with data within minutes. That's all to it.