Monitor Roku

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 Roku SDK, as described below.

Supported Features:

• Engagement metrics
• Quality of Experience Metrics
• Custom Dimensions

Video Quality metrics are not available.

1Include the Mux Data SDK

Place the SDK file in your libs folder. The latest version of the SDK can be found here:

https://src.litix.io/roku/1/mux-analytics.brs

2Setup 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>

3Setup 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.

m.mux = m.top.CreateNode("mux")
m.mux.setField("video", m.video)

muxConfig = {
  property_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.

4Debugging

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

5Make 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. 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

6Advertising 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

7Additional 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 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.

Release notes

Current Release

v1.3.0

Updates:

• Add drmType property to the Mux node. This value is automatically reported from the player if available (#44)
• Add droppedFrames property to the Mux node. This value is must be reported from your player. (#44)
• Add errorContext field to Error Events. This value is automatically reported from the player if available (#44)

Previous Releases

v1.2.1

• Fixes an issue that could cause incorrect playback reporting when seeking occurs during a view and updated the SDK testing infrastructure.

v1.2.0

• Remove auto-generated video_id value; applications should pass their own video_id in the metadata.

v1.1.1

• Fix an issue where an invalid value provided for player_init_time could cause the application to crash.

v1.1.0

• Add support for custom dimensions

v1.0.3

• Fix an issue where properties from the Roku application (such as Director) that are not string types crash the application
• Fix an issue with the sample application running ads

v1.0.2

• Fix an issue where viewer_device_model was not populated correctly.

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.

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 un-minified 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, the 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