Maestro Panel SDK for Roku

Introduction

Welcome to the Maestro Panel Component Library for Roku! This SDK provides a powerful and flexible set of tools to manage content panels, key play data, and overlays within your Roku application. Whether you're building a media streaming app, a gaming interface, or an interactive experience, this library simplifies the process of displaying dynamic content and handling user interactions.

This document is designed to guide you through every step of integrating the Maestro Panel Component Library into your Roku application. It includes detailed installation instructions, a breakdown of all exposed interfaces (functions, observable fields, and configurable fields), practical examples, and tips for troubleshooting common issues.

Prerequisites

Before you begin, ensure you have the following:

A Roku developer account and access to the Roku Developer Dashboard. A Roku device or emulator set up for development. Basic familiarity with Roku SceneGraph (BrightScript and XML). A text editor or IDE (e.g., Visual Studio Code with the Roku extension).

Installation Instructions

Integrating the Maestro Panel Component Library into your Roku application is straightforward. Follow these steps to get started:

Step 1: Add the ComponentLibrary Node

The Maestro Panel SDK is delivered as a remote component library. To use it, you need to create a ComponentLibrary node in your application and point it to the library’s URL.

To use the Maestro Panel SDK in your Roku channel, create a ComponentLibrary node in your BrightScript file (e.g., main.brs or a custom component):

m.componentLibrary = createObject("roSGNode", "ComponentLibrary")
m.componentLibrary.uri = "https://roku-sdk.us-central1-master.gcp.maestro.io/1.1.2/maestrokit.zip"
m.componentLibrary.observeField("loadStatus", "onLibraryLoadStatusChanged")

Explanation

uri: Set this to the Maestro Panel SDK URL. Make sure to update the version number (1.1.2) to the latest available version when needed.

observeField("loadStatus", ...): Use this to track the library's load status. You'll be notified when the SDK is ready to use or if it fails to load.

loadStatus Field Values

"loading" – SDK is currently being downloaded and initialized. "ready" – SDK has successfully loaded and is ready to use. "failed" – An error occurred while loading the SDK.

Always wait for the loadStatus to be "ready" before accessing any components or features provided by the SDK.

Step 2: Instantiate the Maestro Panel

Once the library is loaded, create an instance of the MaestroPanel and attach it to your scene. Define a callback function to handle the loadStatus change:

sub onLibraryLoadStatusChanged()
    if m.componentLibrary.loadStatus = "ready"
        ' Create the MaestroPanel instance
        m.lib = createObject("roSGNode", "MaestroPanelLib:MaestroPanel")
        ' Set up observers for key events
        m.lib.observeField("selectedClipInfo", "onSelectedClipInfo")
        m.lib.observeField("focusedClipIndex", "onFocusedClipIndex")
        m.lib.observeField("focusedTabItem", "onFocusedTabItem")
        ' Add the panel to the scene
    m.top.appendChild(m.lib)
        else if m.componentLibrary.loadStatus = "failed"
        print "Error: Failed to load Maestro Panel library"
    end if
end sub

MaestroPanel Exposed Interfaces

The MaestroPanel component exposes a variety of interfaces to customize its behavior, manage content, and respond to user interactions. These are divided into Functions, Observable Fields, and Configurable Fields.

MaestroPanel Exposed Interfaces

The MaestroPanel provides a rich set of fields and functions to interact with the panel, manage content, and handle overlays.

Functions

Function Name	Description
deauthenticateUser()	Clears or resets the authenticateUser data to null

Observable Fields

| Field ID                | Type            Description                                                                 |
|-------------------------|------------|-----------------------------------------------------------------------------|
| `focusedTabItem`        | Integer    | Index of the currently focused tab when navigating between tabs            |
| `focusedClipIndex`      | assocArray    | Return currently selected index and detail of focused clip                   |
| `selectedClipInfo`      | assocArray    | Return currently selected index and detail of selected click                |
| `didShowOverlay`        | String     | Returns the bet ID of the overlay shown to the app                         |
| `didHideOverlay`        | Boolean    | Returns `true` if the overlay is hidden, otherwise `false`      
           |

Configurable Fields

| Field ID                         | Type       | Description                                                                 |
|----------------------------------|------------|-----------------------------------------------------------------------------|
| width                            | Integer    | Sets the width of the panel (e.g., `1280`)                                  |
| height                           | Integer    | Sets the height of the panel (e.g., `720`)                                  |
| keyPlaysData                     | AssocArray | Sets key play data as an associative array                                  |
| showPanel                        | Boolean    | `true` to show the panel, `false` to hide it                                |
| playClip                         | Integer    | Triggers playback of a clip by specifying its index                         |
| didUpdatePlaybackProgressOfClip  | AssocArray | Tracks playback progress updates (e.g., `{ clipId: "id", progress: 0.75 }`) |
| showLoading                      | Boolean    | Displays the loading state of the panel                                     |
| failedClipId                     | String     | ID of the clip that failed to load                                          |
| authenticateUser                 | AssocArray | Authenticates a user with data (e.g., `{ swid: "xyz", jwt: "abc" }`)        |
| overyConfig                      | AssocArray | Configures overlay coordinates (e.g., `{ x: 300, y: 400 }`)                 |

Example Usage

Setting Panel Size

m.lib.width = 1280
m.lib.height = 720

Showing or Hiding the Panel

m.lib.showPanel = true  ' Show the panel
m.lib.showPanel = false ' Hide the panel

Loading Key Play Data

To display the Key Plays panel in the SDK, you can pass the required data using the

m.lib.keyPlaysData = {
  // your key plays data goes here
}

Once this object is set, the SDK will use it to render the Key Plays panel with the provided content. This must be set after the SDK is loaded, and before attempting to open the Key Plays panel.

Listening for Tab Focus Changes

function onFocusedTabItem(event as Object)
    focusedIndex = event.getData()
    print "Current Focused Tab Index: " + focusedIndex.toStr()
end function

Tracking Playback Progress

function onDidUpdatePlaybackProgressOfClip(event as Object)
    progressData = event.getData()
    print "Clip ID: " + progressData.clipId + " Progress: " + progressData.progress.toStr()
end function

Authenticating a User

To enable betting and fantasy API calls, the SDK requires authentication information in the form of swid and jwt tokens. These values must be set using the m.lib.authenticateUser object after loading the SDK.

m.lib.authenticateUser = { swid: "***************", jwt: "******************" }

Once these values are initialized, the SDK will automatically include them in all relevant API calls related to betting and fantasy features. Ensure you set them only after the SDK has been successfully loaded.

Assigning swid and jwt to m.lib.authenticateUser will not trigger any immediate action. It simply stores the values, and the SDK will retrieve them when needed for internal API requests.

Deauthenticating a User

m.lib.callFunc("deauthenticateUser", invalid)  ' Clears authentication data

Configuring an Overlay

m.lib.overyConfig = { x: 300, y: 400 }  ' Set overlay position

Listening for Overlay Events

function onDidShowOverlay(event as Object)
    betId = event.getData()
    print "Overlay shown for Bet ID: " + betId
end function

function onDidHideOverlay(event as Object)
    isHidden = event.getData()
    if isHidden
        print "Overlay hidden"
    end if
end function

Best Practices

Validate Inputs: Always check that associative arrays (e.g., keyPlaysData, authenticateUser) contain the required keys before assigning them.

Error Handling: Monitor failedClipId and loadStatus to catch and handle errors gracefully.

Performance: Avoid setting showLoading to true unnecessarily, as it may confuse users if no actual loading is occurring.

Testing: Test on multiple Roku devices (e.g., Roku Stick, Roku TV) to ensure compatibility with different screen sizes and resolutions.

Troubleshooting

Library Won’t Load: Verify the uri is correct and your Roku device has an internet connection. Check the console for error messages.

Panel Not Visible: Ensure showPanel is true and the panel is appended to the scene (m.top.appendChild(m.lib)).

Callbacks Not Triggering: Confirm you’ve correctly set up observeField with the right field names and callback functions.

Overlay Misaligned: Double-check overyConfig coordinates and ensure they fit within the panel’s width and height.