Installation and Integration with Maestro Roku SDK

This section will walk you through the process of installing and integrating the Maestro Roku SDK into your Roku application.

Prerequisites

Before you begin, ensure you have:

• Roku Developer Account
• Roku Device in Developer Mode
• Familiarity with SceneGraph XML + BrightScript
• Ability to sideload and inspect logs

Installation

1. Load the Library

The SDK is distributed as a remote ComponentLibrary.

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

2. Check loadStatus

Monitor the library load status to ensure it loads successfully:

Value	Meaning
"loading"	Downloading and initializing
"ready"	Successfully loaded; safe to use
"failed"	Error while loading

Basic Integration Steps

1. Create and Append the Maestro Panel

Once the library is loaded, create the MaestroPanel instance, set up observers, and append it to your scene:

sub onLibraryLoadStatusChanged()
    if m.componentLibrary.loadStatus = "ready"
        ' Create MaestroPanel instance
        m.lib = createObject("roSGNode", "MaestroPanelLib:MaestroPanel")

        ' Set up observers for essential events
        m.lib.observeField("showPanel", "onShowPanel")
        m.lib.observeField("handleLoadingSceneAction", "onHandleLoadingSceneAction")
        m.lib.observeField("focusedTabItem", "onFocusedTabItem")
        m.lib.observeField("trackingEvent", "onTrackingEvent")
        m.lib.observeField("userRequestedLogin", "onUserRequestedLogin")

        ' Append to scene BEFORE setting config
        m.top.appendChild(m.lib)

        ' Now configure the SDK
        finishSetup()
    end if
end sub

danger

Always append the panel to your scene (m.top.appendChild(m.lib)) BEFORE setting the config. The config triggers API requests that require the panel to be part of the scene graph.

2. Configure the SDK

Set up the SDK configuration and panel dimensions:

sub finishSetup()
    ' Set panel dimensions
    m.lib.width = 1280
    m.lib.height = 720

    ' Configure the SDK (see interface for full list)
    m.lib.config = {
        siteID:    "your-site-id",
        pageID:    "your-page-id",
        useProdEnv: false
    }

    ' Set initial focus to your UI
    m.yourUIElement.setFocus(true)
end sub

The config object is the primary configuration for the SDK:

Config Key	Type	Description
siteID	string	Environment identifier (client-level)
eventID	string	Live or VOD event identifier
pageID	string	ID associated with a Maestro Page
authToken	string	User auth token
swid	string	User ID
useProdEnv	boolean	Choose production or QA API environment

note

The config object can be passed any parameter. This object is passed directly into each panel. Each panel will have different requirements—it's up to you to pass what's needed. siteID, useProdEnv,pageID or eventID are required parameters.

3. Show and Hide the Panel

Control panel visibility using the showPanel field:

' Show the panel
m.lib.showPanel = true
m.lib.callFunc("setPanelFocus")

' Hide the panel
m.lib.showPanel = false

4. Handle Panel Events

Observe and respond to panel state changes:

' Called when showPanel changes
sub onShowPanel(event)
    isPanelShown = event.getData()
    if isPanelShown
        ' Panel is now visible
        m.lib.callFunc("setPanelFocus")
    else
        ' Panel is hidden
        m.yourUIElement.setFocus(true)
    end if
end sub

' Handle SDK loading actions (e.g., returning focus)
sub onHandleLoadingSceneAction(event)
    action = event.getData()
    if action = "returnFocus"
        ' User exited the panel, return focus to your UI
        m.yourUIElement.setFocus(true)
    end if
end sub

5. Cleanup

Always destroy the SDK when exiting your video session:

sub cleanup()
    if m.lib <> invalid
        m.lib.callFunc("destroySDK")
        m.top.removeChild(m.lib)
        m.lib = invalid
    end if
    if m.componentLibrary <> invalid
        m.componentLibrary = invalid
    end if
end sub

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

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.