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.
1. Getting Started
This documents integration instructions for Roku. For other players, see the additional Integration Guides.
2. Architecture
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.
3. Include the SDK
Place the SDK file in your libs folder. The latest version of the SDK can be found at https://src.litix.io/roku/1/mux-analytics.brs.
4. 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.
<component name="MuxTask" extends="Task">
<interface>
<field id="video" type="node" alwaysNotify="true"/>
<field id="config" type="assocarray" alwaysNotify="true"/>
<field id="rafEvent" type="assocarray" alwaysNotify="true"/>
<field id="error" type="assocarray" alwaysNotify="true"/>
<field id="view" type="String" alwaysNotify="true"/>
<field id="exit" type="Boolean" alwaysNotify="true"/>
<field id="exitType" type="String" alwaysNotify="true" value="hard" />
</interface>
<script type="text/brightscript" uri="pkg:/libs/mux-analytics.brs"/>
</component>
5. 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.
m.mux = m.top.CreateNode("mux")
m.mux.setField("video", m.video)
muxConfig = {
property_key: "EXAMPLE_PROPERTY_KEY",
}
m.mux.setField("config", muxConfig)
m.mux.control = "RUN"
' Load the video into the Video node
6. Test It
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 property_key and look for video views.
Note that it may take a few minutes for views to show up in the Mux Data dashboard.
7. 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.
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
:
[mux-analytics] EVENT playerready
Property set to full
:
[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
:
[mux-analytics] BEACON (2) [ playerready viewstart ]
Property set to full
:
[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
8. Add Metadata
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. 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, 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
9. Advertising Configuration
If advertising is to be used, you must send the appropriate events to the Mux Task, as shown below.
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")
m.mux.setField("rafEvent", {obj:obj, eventType:eventType, ctx:ctx})
end function
10. Additional Configuration
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.
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 afterwards.
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.
Release Notes
Current Release
v1.0.1
- Fix an issue where the player playhead position was not reported. This has no impact on collected metrics, but fixes a display issue within the dashboard when viewing individual views.
Previous Releases
v1.0.0
- Fix an issue where
viewer_user_id
was overwritten unintentionally. - Fix an issue where
player_mux_plugin_name
and device type were set incorrectly. - Fix an issue where the
seeked
event was incorrectly named. - Provide updated device information to match the intended uses for each field.
- Fix an issue where certain metrics (large numbers) were sent in scientific notation, causing incorrect values to be stored.
- Fix an issue where error code and message were incorrectly sent with
aderror
events.
v0.2.0
- Remove the debug option of
mux_minification
. If you set this, it will have no action. Instead, all events and beacons will be logged in an unminified version, while everything will be sent to the Mux backend minified. - Update such that
player_instance_id
(controlled by the Mux SDK) is sent as a GUID rather than a different format of ID.
v0.1.0
- Add
exitType
configuration option - Fix an issue where source duration is reported incorrectly
- Fix an issue where on certain devices rebuffer percentage could be reported incorrectly (e.g. extremely high)
- Fix an issue where
watch_time
may have been calculated incorrectly in certain situations - Fix an issue to allow correctly tracking exits before video start
Updated 3 months ago