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/3.1.0/maestrokit.zip"
m.componentLibrary.observeField("loadStatus", "onLibraryLoadStatusChanged")
Explanation
uri: Set this to the Maestro Panel SDK URL. Make sure to update the version number (3.1.0) 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
Define a callback function to handle the loadStatus change: Once the library is loaded, create an instance of the MaestroPanel and attach it to your scene.
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("focusedTabItem", "onFocusedTabItem")
m.lib.observeField("selectedClipInfo", "onSelectedClipIndex")
m.lib.observeField("focusedClipIndex", "onFocusedClipIndex")
m.lib.config = {
"siteId": "",
"eventId": "",
"swId": "",
"authToken": ""
}
' Add the panel to the scene
m.top.appendChild(m.lib)
m.settingConfig.setFocus(true)
m.clipId = getCurrentClipId(0)
playVideo()
maxVideo()
m.index = 0
end if
end sub
Setting the config field will trigger the request to hit the maestro config for the specified eventID. The config will determine what panels will be built. The setting of any other configurable fields should be done before the setting of the config parameter to ensure those fields are populated when panels are built.
The userDidStartWatchingEvent can be used when the config parameter has already been set and a user switches content.
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.
Functions
| Function Name | Description |
|---|---|
setPanelFocus | Call for setting focus to the Maestro Panel |
Observable Fields
| Field ID | Type Description |
|-------------------------|------------|-----------------------------------------------------------------------------|
| focusedTabItem | Integer | Index of the currently focused tab when navigating between tabs |
| focusedClipIndex | assocArray | Returns currently selected index and detail of focused clip |
| selectedClipInfo | assocArray | Returns 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` |
| userRequestedLogin | Boolean | Returns `true` if the user click on my disney login otherwise `false` |
| userViewedPanel | assocArray | Returns a panel name when that panel has been shown |
| trackingEvent | assocArray | Returns events tracking user interactions within the SDK. |
| showLoading | Boolean | Displays the loading state of the panel |
| failedClipId | String | ID of the clip that failed to load |
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`) |
| fetchDataOnInit | Boolean | `true` by default. When `false` fetch data on focus of associated panel |
| generateQRCode | Boolean | `true` by default. When `false` a short URL will be displayed |
| userDidStartWatchingEvent | String | An eventID associated with this content session, panels build on setting |
| config | assocArray | Object associated with requirements for API calls. When set, fetch maestro config |
| config.eventID | string | An eventID associated with this content session |
| config.authToken | string | authToken associated with the current user |
| config.swid | string | SWID associated with the current user |
| config.useProdEnv | boolean | Falg to use production or qa environment, true by default |
| config.siteId | string | Unique ID for each client |
### Client Action Fields
```python
| Field ID | Type | Description |
|----------------------------------|------------|-----------------------------------------------------------------------------|
| keyPlaysData | AssocArray | Sets key play data as an associative array |
| showPanel | Boolean | `true` to show the panel, `false` to hide it |
| gameState | String | pre | in | post Set the state of the game for stats panel |
| jumpToClipIdByIndex | Integer | Jump to the key play at associated index |
| jumpToClipId | Integer | Jump to key play at associated ID |
| updatePlaybackProgressOfClip | AssocArray | As Key plays are viewed set progress of clip to panel so UI can update |
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 authToken tokens. These values must be set using the m.lib.config object after loading the SDK.
m.lib.config.swid = "swidString"
m.lib.config.authToken = "token"
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.
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.