Introduction:

FastPix Roku Data Core SDK monitors and analyzes Roku SceneGraph Video node playback. Get instant insights into video performance with our monitoring features:

• Real-time stream analytics (manifest loading, segments, quality switches)
• Player performance data (startup time, buffering, quality)
• Network metrics (bandwidth, request timing)
• Error logs and diagnostics
• User interaction events

The SDK instantly collects and sends all metrics to the FastPix dashboard for easy viewing.

Looking for the full integration walk-through? See INTEGRATION.md for the complete guide — interface reference, metadata schema, lifecycle patterns, event reference, and troubleshooting.

Prerequisites:

Getting Started

To begin tracking your video analytics, you'll need your FastPix workspace key. Here's how to get it:

1. Sign up or login to FastPix Dashboard.
2. Navigate to the workspace page.
3. Copy your preferred workspace key.

You'll also need:

• A Roku device with Developer Mode enabled
• A SceneGraph channel project (with manifest, source/, components/)
• Roku OS 9.1 or newer

That's it! You're ready to integrate the SDK into your Roku channel.

Step 1: Installation and Setup:

The SDK ships as source files — there is no Roku package manager. Copy the two SDK trees into your channel:

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

Your channel layout should look like this after copying:

your-channel/
  manifest
  source/
    main.brs
    fastpix/                       ← copied from SDK
  components/
    fastpix/                       ← copied from SDK

Step 2: Declare the Tracker

In whichever scene component owns your Video node, add a <FastPixTracker> sibling:

<?xml version="1.0" encoding="utf-8" ?>
<component name="MyPlayerScene" extends="Scene">
    <children>
        <Video id="player"
               translation="[0, 0]"
               width="1920"
               height="1080" />

        <FastPixTracker id="fp"
                        workspaceId="YOUR_WORKSPACE_KEY"
                        debug="false"
                        beaconDomain="anlytix.io" />
    </children>

    <script type="text/brightscript" uri="MyPlayerScene.brs" />
</component>

Replace YOUR_WORKSPACE_KEY with your FastPix workspace key.

Step 3: Basic Integration

The workspaceId is a mandatory field that must be provided. Wire the Video node into the tracker in your scene's init():

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

sub playVideo(videoMetadata as object)
    ' Custom dimensions for tracking
    m.fp.data = {
        workspace_id:      "WORKSPACE_KEY"        ' Unique key to identify your workspace
        player_name:       "Main Video Player"    ' A custom name or identifier for this player instance
        player_init_time:  FastPix_Now()          ' Timestamp of when the player was initialized
        video_title:       "VIDEO_TITLE"          ' Title of the video being played
        video_id:          "VIDEO_ID"             ' Unique identifier for the video
        viewer_id:         "VIEWER_ID"            ' Unique identifier for the viewer
        video_stream_type: "on-demand"            ' Type of streaming (live / on-demand)

        ' Add any additional dimensions
    }

    ' 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 so playerReady /
    ' viewBegin fire before the first frame
    m.fp.control     = "start"
    m.player.control = "play"
    m.player.SetFocus(true)
end sub

Once the player has loaded the URL and playback has started, the SDK will begin tracking the analytics. After playback ends, you can view the complete analytics report on your FastPix dashboard.

Step 4: Enhance Tracking with User Passable Metadata

Check out the user-passable metadata documentation to see the metadata supported by FastPix. You can use custom metadata fields like custom_1 to custom_10 for your business logic, giving you the flexibility to pass any required values. Named attributes, such as video_title and video_id, can be passed directly as they are.

sub init()
    m.player = m.top.findNode("player")
    m.fp     = m.top.findNode("fp")
    m.fp.video = m.player

    ' Custom metadata for tracking
    m.fp.data = {
        workspace_id:       "WORKSPACE_KEY"        ' Unique key to identify your workspace
        player_name:        "Main Video Player"    ' A custom name or identifier for this player instance
        player_init_time:   FastPix_Now()          ' Timestamp of when the player was initialized
        video_title:        "Test Content"         ' Title of the video being played
        video_id:           "f01a98s76t90p88i67x"  ' A unique identifier for the video
        viewer_id:          "user12345"            ' A unique identifier for the viewer
        video_content_type: "series"               ' Type of content (e.g., series, movie)
        video_stream_type:  "on-demand"            ' Type of streaming (live / on-demand)

        ' Custom fields for additional business logic
        custom_1: ""    ' Use this field to pass any additional data needed for your specific business logic
        custom_2: ""    ' Use this field to pass any additional data needed for your specific business logic

        ' Add any additional metadata
    }

    m.fp.control     = "start"
    m.player.control = "play"
end sub

' To stop monitoring
' m.fp.control = "stop"

Note:

Keep metadata consistent across different video loads to make comparison easier in the dashboard.

Step 5: Advanced Customization with FastPix Data SDK

Attribute	Description	Type	Example Usage
disableCookies	FastPix Data SDK persists a viewer/session ID in roRegistrySection by default to track playback across channel launches and identify unique viewers. If your channel cannot write to the registry, you can disable this feature by setting disableCookies="true". This ensures no registry writes happen, enhancing privacy and compliance with user preferences.	Boolean	disableCookies="true"
respectDoNotTrack	Set to true to honor users' privacy preferences. Acts as a hard kill switch — suppresses every beacon. Roku has no native DNT signal, so the flag itself is the toggle.	Boolean	respectDoNotTrack="true"
automaticErrorTracking	FastPix automatically tracks errors that occur during playback failures (Video.errorCode non-zero). To disable this feature, set automaticErrorTracking="false". This gives you more control over which errors are considered fatal and helps you manage error reporting according to your channel's needs.	Boolean	automaticErrorTracking="false"
debug	Set to true to enable SDK diagnostic logs on the BrightScript console (telnet <roku-ip> 8085) for troubleshooting.	Boolean	debug="true"

<FastPixTracker id="fp"
                workspaceId="WORKSPACE_KEY"
                debug="true"
                disableCookies="true"
                respectDoNotTrack="true"
                automaticErrorTracking="false" />

m.fp = m.top.findNode("fp")
m.fp.video = m.top.findNode("player")
m.fp.data = {
    workspace_id: "WORKSPACE_KEY"   ' Replace with your actual workspace key

    ' ... add other metadata as needed
}
m.fp.control = "start"

Step 6: Emit Custom Events

Advanced Error Reporting and Contextual Tracking

By default, FastPix tracks errors that occur during playback failures. However, you can also emit a custom error event for non-severe issues that arise outside of these failures, allowing you to provide additional context for tracking purposes.

' m.fp is the FastPixTracker component
m.fp.dispatch = {
    name: "error"
    data: {
        player_error_code:    1024                                ' Custom error code
        player_error_message: "Description of error"              ' Generalized error message
        player_error_context: "Additional context for the error"  ' Instance-specific information
    }
}

Changing video streams in player

When your channel plays multiple videos back-to-back in the same player, it's essential to notify the FastPix SDK whenever a new video starts; possibly in scenarios like playlist content / video series or any other video the user wants to play.

' m.fp is the FastPixTracker component
m.fp.dispatch = {
    name: "videoChange"
    data: {
        video_id:     "abc345"                  ' Unique identifier for the new video
        video_title:  "My Other Great Video"    ' Title of the new video
        video_series: "Weekly Great Videos"     ' Series name if applicable

        ' Additional metadata can be included here
    }
}

The SDK closes the previous view (sends viewCompleted), creates a new view_id, and starts a fresh view — no need to stop/start the tracker.

Detailed Usage:

For the complete integration walk-through — including the full <FastPixTracker> interface reference, metadata schema, lifecycle patterns, event reference, and troubleshooting — see INTEGRATION.md.

For more detailed steps and advanced usage, please refer to our official documentation:

• Roku Monitoring Documentation
• User Passable Metadata