Monitor Roku

This guide explains how to add FastPix video analytics to a Roku channel. It walks you through installation, a minimal three-step integration, the complete configuration reference, and troubleshooting.

Before you begin

Make sure you have the following:

• A Roku device with Developer Mode enabled.
• A SceneGraph channel project that includes a manifest, a source/ directory, and a components/ directory.
• A FastPix workspace ID. The SDK uses this value as the beacon subdomain.
• Roku OS 9.1 or later.

How the SDK works

The FastPix Data Core SDK observes a SceneGraph Video node and translates Roku state transitions into FastPix events. As playback proceeds, the SDK accumulates view-level quality-of-experience (QoE) metrics such as watch time, rebuffer count, rebuffer duration, rebuffer percentage, seek count, time to first frame, throughput, and scaling ratio and sends them as compact JSON beacons to a FastPix collector.

The SDK is wire-compatible with the FastPix Web SDK, so the same backend ingests data from both. You don’t need to make any backend changes.

Add the SDK files to your channel

The SDK ships as BrightScript source files. There is no Roku package manager, so you copy two directory trees directly into your channel.

To install the SDK, copy the fastpix folders from the SDK into your channel’s source/ and components/ directories:

$
cp -R source/fastpix      /path/to/your-channel/source/
$
cp -R components/fastpix  /path/to/your-channel/components/

After you copy the files, your channel structure looks like this:

your-channel/
  manifest
  source/
    main.brs
    fastpix/                       # Copied from the SDK
      FastPixCore.brs
      FastPixConstants.brs
      FastPixUtils.brs
      FastPixIdGeneration.brs
      FastPixListenerManager.brs
      FastPixFieldMap.brs
      FastPixFormatter.brs
      FastPixDeviceInfo.brs
      FastPixRegistry.brs
      FastPixDebug.brs
      FastPixState.brs
      FastPixPlaybackEventHandler.brs
      FastPixConnectionHandler.brs
      monitors/
        FastPixErrorManager.brs
        FastPixVideoStateObserver.brs
        FastPixPlayheadObserver.brs
        FastPixVideoSeekTracker.brs
        FastPixVideoBufferMonitor.brs
        FastPixWallClockTimeTracker.brs
        FastPixPlaybackProgressMonitor.brs
        FastPixPlaybackStartupMonitor.brs
        FastPixVideoResolutionHandler.brs
        FastPixRequestMetricsMonitor.brs
  components/
    fastpix/                       # Copied from the SDK
      FastPixTracker.xml
      FastPixTracker.brs
      FastPixBeaconTask.xml
      FastPixBeaconTask.brs

That completes the installation. You don’t need to vendor anything else.

Important: Copy every file under source/fastpix/ and components/fastpix/. A missing file prevents the component from loading and causes a compile error when you sideload.

Integrate the tracker

After you install the SDK, complete the following three steps to start tracking playback.

Declare the tracker in your scene XML

In the scene component that owns your Video node, add a <FastPixTracker> element as a sibling of the Video node. Replace YOUR_WORKSPACE_ID with your FastPix workspace key.

1
<?xml version="1.0" encoding="utf-8" ?>
2
<component name="MyPlayerScene" extends="Scene">
3
    <children>
4
        <Video id="player"
5
               translation="[0, 0]"
6
               width="1920"
7
               height="1080" />
8
9
        <FastPixTracker id="fp"
10
                        workspaceId="YOUR_WORKSPACE_ID"
11
                        debug="false"
12
                        beaconDomain="anlytix.io" />
13
    </children>
14
15
    <script type="text/brightscript" uri="MyPlayerScene.brs" />
16
</component>

Wire the Video node in your scene’s init()

Tell the tracker which Video node to observe. Set the video field before you start the tracker.

sub init()
    m.player = m.top.findNode("player")
    m.fp     = m.top.findNode("fp")
    ' Required: tell the tracker which Video node to observe.
    m.fp.video = m.player
end sub

Set metadata and start tracking before play

Set the per-video metadata, start the tracker, and then start playback. Start the tracker before you play the video so that the playerReady and viewBegin events fire before the first frame.

sub playVideo(videoMetadata as object)
    ' Set per-video metadata. See the metadata schema for the full field list.
    m.fp.data = {
        video_id:          videoMetadata.id
        video_title:       videoMetadata.title
        viewer_id:         m.global.userId       ' Your viewer ID
        video_stream_type: "on-demand"
        player_name:       "MyChannel Player"
        player_version:    "1.0.0"
    }
    ' Build the Roku content node.
    content = CreateObject("roSGNode", "ContentNode")
    content.url          = videoMetadata.streamUrl
    content.streamFormat = "hls"
    m.player.content     = content
    ' Order matters: start the tracker before play.
    m.fp.control     = "start"
    m.player.control = "play"
    m.player.SetFocus(true)
end sub
sub stopVideo()
    m.player.control = "stop"
    m.fp.control     = "stop"
end sub

After you complete these steps, the SDK emits beacons to https://YOUR_WORKSPACE_ID.anlytix.io for every state change, plus a heartbeat every 10 seconds during steady playback.

FastPixTracker interface reference

The <FastPixTracker> component exposes input fields that you set from your channel and output fields that you can observe. Every field is optional unless it’s marked as required.

Input fields

These fields pass data from your channel to the SDK.

Output fields

You can observe these fields to monitor the SDK from your channel.

Use the output fields to build an in-app debug overlay or to detect persistent transport failures:

m.fp.observeField("lastBeaconStatus", "onBeaconStatus")
sub onBeaconStatus()
    if m.fp.lastBeaconStatus >= 400
        print "[App] FastPix transport error: "; m.fp.lastBeaconError
    end if
end sub

Metadata schema

Set the m.fp.data associative array before you set m.fp.control to "start". The keys in the following tables are the ones that the FastPix dashboard recognizes. The SDK passes through any other keys that you add, which is useful for custom attributes.

Identity

Player

Stream

Custom attributes

Auto-populated fields

The SDK sets the following fields automatically. Don’t set them yourself.

Lifecycle patterns

The way you manage the tracker depends on whether you play a single video, a playlist, or swap content within a single tracker.

Play a single video and then exit

Start the tracker and player, and then stop both when playback ends. Setting control to "stop" flushes the final viewCompleted beacon.

m.fp.data = { video_id: "abc", video_title: "Demo" }
m.fp.control     = "start"
m.player.control = "play"
' ... user watches ...
m.player.control = "stop"
m.fp.control     = "stop"     ' Flushes the final viewCompleted beacon

Play a playlist

For each new video, stop the tracker, set the new metadata, and restart the tracker.

sub onPlayNext(videoMetadata as object)
    ' Tear down the previous view. This sends viewCompleted.
    m.fp.control     = "stop"
    m.player.control = "stop"
    ' Configure the next video.
    m.fp.data = {
        video_id:    videoMetadata.id
        video_title: videoMetadata.title
        ' ... etc.
    }
    content = CreateObject("roSGNode", "ContentNode")
    content.url          = videoMetadata.streamUrl
    content.streamFormat = "hls"
    m.player.content     = content
    m.fp.control     = "start"
    m.player.control = "play"
end sub

Swap content within a single tracker

To load a new video into the same tracker, for example, when you move from one episode to the next in the same UI fire a videoChange event with the dispatch field.

m.fp.dispatch = {
    name: "videoChange"
    data: {
        video_id:    nextEpisode.id
        video_title: nextEpisode.title
        video_source_url: nextEpisode.streamUrl
    }
}

When you fire a videoChange event, the SDK closes the previous view by sending a viewCompleted beacon, creates a new view_id, and starts a fresh view. You don’t need to stop and restart the tracker.

Fire custom events

To fire a custom event, set m.fp.dispatch to { name: "<eventName>", data: { ... } }. The following events are available to fire from your channel.

Note: Don’t fire playback events such as play, playing, or buffering directly. The SDK derives these events from Video.state automatically.

Emitted events reference

The SDK emits the following events, which appear as event_name=... in each beacon body. A full state event carries the complete view state, and a delta event carries only changed fields.

Verify the integration

After you integrate the SDK, verify that beacons reach your workspace by using the dashboard, the telnet debug console, or in-app observers.

Check the FastPix dashboard

1. Sideload your channel and play a video for about 30 seconds.
2. Open the real-time view in your FastPix workspace dashboard.

Within about 15 seconds of the first beacon, the view appears with a Playing status. As the view progresses, the dashboard updates with real metrics.

Use the telnet debug console

Set debug="true" on the tracker, and then connect to the BrightScript console:

$
telnet <roku-ip> 8085

With debugging enabled, the console prints output similar to the following:

[FastPix] tracker started workspaceId=... beaconUrl=https://...anlytix.io
[FastPix] dispatch -> configureView
[FastPix] dispatch -> playerReady
[FastPix] queue beacon: playerReady view=<uuid> playhead=0ms
[FastPix] Video.state none -> buffering
[FastPix] dispatch -> loadstart
[FastPix] Video.state buffering -> playing
[FastPix] dispatch -> play
[FastPix] dispatch -> playing
[FastPix] POST https://...anlytix.io batch=4 bytes=2347
[FastPix] beacon response code=200 rtt=87ms

Use in-app observers

Observe the lastBeaconStatus and lastBeaconError fields on the tracker to build an in-app debug overlay. This approach is useful in shipped builds where telnet isn’t available. For an example, see Output fields.

Troubleshoot common issues

Complete example

Drop the following three files into a fresh Roku channel, alongside the SDK trees that you copied in the install step, to create a working integration.

source/main.brs:

sub Main()
    screen = CreateObject("roSGScreen")
    port = CreateObject("roMessagePort")
    screen.SetMessagePort(port)
    screen.CreateScene("MyPlayerScene")
    screen.Show()
    while true
        msg = wait(0, port)
        if type(msg) = "roSGScreenEvent"
            if msg.IsScreenClosed() then exit while
        end if
    end while
end sub

components/MyPlayerScene.xml:

1
<?xml version="1.0" encoding="utf-8" ?>
2
<component name="MyPlayerScene" extends="Scene">
3
    <children>
4
        <Video id="player" width="1920" height="1080" />
5
        <FastPixTracker id="fp"
6
                        workspaceId="YOUR_WORKSPACE_ID"
7
                        debug="true" />
8
    </children>
9
    <script type="text/brightscript" uri="MyPlayerScene.brs" />
10
</component>

components/MyPlayerScene.brs:

sub init()
    m.player = m.top.findNode("player")
    m.fp     = m.top.findNode("fp")
    m.fp.video = m.player
    m.fp.data = {
        video_id:          "demo-001"
        video_title:       "Demo Video"
        viewer_id:         "demo-viewer"
        video_stream_type: "on-demand"
        player_name:       "Demo Player"
        player_version:    "1.0.0"
    }
    content = CreateObject("roSGNode", "ContentNode")
    content.url          = "https://test-streams.fastpix.dev/x36xhzz/x36xhzz.m3u8"
    content.streamFormat = "hls"
    m.player.content     = content
    m.fp.control     = "start"
    m.player.control = "play"
    m.player.SetFocus(true)
end sub

For a complete reference channel that includes a picker, playback, and a debug overlay, see samples/host-channel/ in the SDK repository.

Advanced configuration

Use the following patterns to extend your integration.

• Multiple players per scene: Instantiate one <FastPixTracker> per Video node. Trackers don’t share state.
• A/B testing: Vary the experiment_name value in m.fp.data per session.
• Custom dimensions: Any unknown key that you add to m.fp.data rides every beacon. Use custom_1 through custom_10 for dimensions that you want the FastPix dashboard to surface as filterable.
• Final flush: The viewCompleted beacon is sent through the Task thread when you set m.fp.control = "stop". The tracker keeps the Task alive long enough for the beacon to land, so you don’t need to wait.
• Registry usage: The SDK uses one roRegistrySection named FastPix. Its footprint is less than 300 bytes.

Get support

To diagnose issues, set debug="true" on the tracker and watch the console with telnet <roku-ip> 8085 while you test. The lastBeaconStatus and lastBeaconError output fields surface the most recent HTTP result for in-app monitoring.