Maestro Event Interface

Introduction

The Maestro Event Interface defines observable fields and client action fields that enable bidirectional communication between your Roku application and the SDK. These fields allow you to monitor SDK events, track user interactions, control panel behavior, and respond to state changes.

Key Responsibilities

The Maestro Event Interface creates a clear contract between your application and the SDK, enabling communication for panel management, analytics tracking, error handling, and user interactions. This interface is core to the SDK's functionality and is designed to work seamlessly with your Roku application's event handling.

• Panel Management: Fields like userViewedPanel, shouldShowPanel, and focusedTabItem allow you to monitor panel visibility and user navigation, enabling proper state management and analytics tracking.

• Error Handling: The errorInformation field provides detailed error reporting from the SDK, allowing you to handle issues gracefully and provide user feedback.

• Analytics Tracking: The trackingEvent field emits a detailed analytics event stream, enabling you to forward SDK events to your analytics platform.

• User Interactions: Fields like userRequestedLogin notify you when users take specific actions that require your application's response.

• Client Actions: Fields like showPanel and openToPanel allow your application to trigger actions in the SDK, controlling panel visibility and navigation.

Observable Fields

Panel Management

These fields allow you to monitor panel visibility and user interactions:

Field	Type	Description
focusedTabItem	integer	Current tab index
onOverlayEvent	assocArray	Overlay lifecycle events (will-appear, did-appear, did-engage, did-dismiss)
onPanelEvent	assocArray	Panel-specific events
panelOpenedThroughOverlay	boolean	Special state: overlay → panel transition
panelsBuilt	boolean	Fires when the SDK finishes building panels; signal to call fetchMaestroModule()
shouldShowPanel	boolean	Panel visibility recommendation
userViewedPanel	assocArray	Emits panel name when opened

State & Tracking

These fields allow you to monitor SDK state, errors, and analytics:

Field	Type	Description
errorInformation	assocArray	Error reporting from SDK
lastDataReceived	assocArray	Liveness signal for the live data poll
trackAction	assocArray	Overlay CTA engagement event (active)
trackImpression	assocArray	Overlay view and dismiss events (passive)
isReady	boolean	SDK initialization state
trackingEvent	assocArray	Detailed analytics event stream
userRequestedLogin	boolean	User tapped "Login" button

Client Action Fields

These fields allow your application to trigger actions in the SDK:

Field	Type	Description
openToPanel	string	Open panel by name ("keyplays", "fantasy", "stats", etc.)
setDataToOverlay	assocArray	Grant or deny overlay display and focus in response to will-appear events
showPanel	boolean	Show/hide the Maestro panel

Usage Pattern

Observable fields should be set up with observeField() to receive notifications:

' Observe panel events
m.lib.observeField("userViewedPanel", "onUserViewedPanel")
m.lib.observeField("focusedTabItem", "onFocusedTabItem")
m.lib.observeField("trackingEvent", "onTrackingEvent")
m.lib.observeField("errorInformation", "onErrorInformation")

' Handle panel view events
function onUserViewedPanel(event as Object)
    panelData = event.getData()
    print "User viewed: " + panelData.panelName
end function

' Control panel visibility (client action)
m.lib.showPanel = true

' Open to specific panel (client action)
m.lib.openToPanel = "keyplays"

Best Practices

• Observe Early: Set up field observers immediately after creating the MaestroPanel node, before setting the config.
• Handle Errors: Always observe errorInformation to catch and handle SDK errors gracefully.
• Track Analytics: Forward trackingEvent data to your analytics platform for comprehensive tracking.
• Respond to User Actions: Implement handlers for userRequestedLogin and other user interaction fields.
• Manage Focus: Use client action fields in combination with the setPanelFocus() function for proper focus management.