Overlay Integration

Overview

This section walks you through integrating overlays into your Maestro Roku SDK implementation. Overlays provide animated, contextual notifications that enhance user engagement during live events.

Integration Steps

1. Handle Overlay Lifecycle Events

The SDK emits lifecycle events through the onOverlayEvent field as overlays move through their display cycle. Observe this field to react to overlay appearance, engagement, and dismissal.

m.lib.observeField("onOverlayEvent", "onOverlayEvent")

function onOverlayEvent(event as Object)
    overlayEvent = event.getData()
    eventType = overlayEvent.type
    payload = overlayEvent.payload

    if eventType = "will-appear"
        ' Grant permission and control focus. Respond within ~100 ms.
        m.lib.setDataToOverlay = {
            overlayId: payload.overlayId
            canAppear: true
            canFocus: false  ' Prevent the overlay from stealing Roku focus
        }

    else if eventType = "did-appear"
        ' Overlay is now visible. Use for analytics or UI state.
        print "Overlay appeared: " + payload.overlayId

    else if eventType = "did-engage"
        ' Viewer pressed OK on the overlay. SDK navigates to the associated panel.
        print "Viewer engaged with overlay: " + payload.overlayId

    else if eventType = "did-dismiss"
        ' Overlay dismissed via timeout or auto-dismiss.
        ' If the overlay held focus and the SDK could not restore it, you must place focus.
        if not payload.focusRestoredBySDK
            m.videoPlayer.setFocus(true)
        end if
    end if
end function

The payload object for each event type contains:

Event	`payload` fields
`will-appear`	`overlayId`, `associatedPanel`, `canAppear`, `canFocus`
`did-appear`	`overlayId`, `associatedPanel`
`did-engage`	`overlayId`, `associatedPanel`
`did-dismiss`	`overlayId`, `associatedPanel`, `focusRestoredBySDK`

Granting or Denying Overlay Appearance

When you receive a will-appear event, control whether the overlay appears and whether it may steal focus by setting setDataToOverlay:

m.lib.setDataToOverlay = {
    overlayId: payload.overlayId,  ' Required — identifies the pending overlay
    canAppear: true,               ' true = display; false = skip this overlay
    canFocus: false                ' true = overlay may take focus; false = overlay appears without focus
}

If you do not set setDataToOverlay within a short window after will-appear, the overlay appears using the defaults provided in the will-appear payload.

Back Key Dismiss

When an overlay has focus, pressing the Back key dismisses it and fires did-dismiss on onOverlayEvent. The key press is consumed by the SDK and does not propagate to the host application.

note

Modal overlays (such as consent or age-gate screens) trap all key events until the viewer presses OK. Pressing Back does not dismiss a modal overlay.

You can also dismiss the visible overlay programmatically by calling dismissOverlay():

' Returns true if an overlay was dismissed, false if none was visible.
dismissed = m.lib.callFunc("dismissOverlay")

2. Track Overlay Analytics

The SDK automatically fires analytics events via the trackingEvent field during the overlay lifecycle. Observe this field to receive overlay events in your analytics pipeline:

m.lib.observeField("trackingEvent", "onTrackingEvent")

function onTrackingEvent(event as Object)
    trackingData = event.getData()
    if trackingData <> invalid
        ' Forward to your analytics service
        yourAnalyticsService.track(trackingData)
    end if
end function

Permission and focus handshake

When a will-appear event fires, the payload includes two default values:

Field	Default	Description
`canAppear`	`true`	Whether the overlay is allowed to appear
`canFocus`	`true`	Whether the overlay may take Roku focus

Respond with setDataToOverlay to override these defaults for a specific overlay. If you do not respond within approximately 100 ms, the SDK uses the defaults and proceeds.

Set canAppear: false to suppress an overlay — for example, while a dialog is on screen:

m.lib.setDataToOverlay = {
    overlayId: payload.overlayId
    canAppear: not m.dialogIsOpen
    canFocus: false
}

Focus management after dismissal

The did-dismiss payload includes focusRestoredBySDK:

true — The SDK restored focus to the panel position it held before the overlay appeared. Do not move focus.
false — The overlay held Roku focus but the SDK could not restore it (for example, the panel was not open). Place focus in the appropriate element for your application.

Analytic tracking events

Three event types are emitted for overlay interactions:

Event type	When it fires
`view`	The overlay becomes visible on screen
`engage`	The user selects the overlay and the associated panel opens
`dismiss`	The overlay is automatically dismissed after its display period expires

2. Trigger Test Overlays

During development, you can trigger test overlays:

' Trigger a fantasy overlay test
m.lib.sendTestOverlay = "fantasy"

' Trigger a bet overlay test
m.lib.sendTestOverlay = "bet"

2. Observe Overlay Analytics Callbacks

The SDK emits flat [String:String] analytics payloads for every overlay lifecycle event. Observe trackAction for active engagement (CTA press) and trackImpression for passive events (view and dismiss):

m.lib.observeField("trackAction", "onOverlayAction")
m.lib.observeField("trackImpression", "onOverlayImpression")

function onOverlayAction(event as Object)
    payload = event.getData()
    ' payload.overlay_event is always "engage"
    ' payload.panel_target contains the panel opened by the CTA, if any
    myAnalytics.track("overlay_action", payload)
end function

function onOverlayImpression(event as Object)
    payload = event.getData()
    ' payload.overlay_event is "view" or "dismiss"
    myAnalytics.track("overlay_impression", payload)
end function

See trackAction and trackImpression for full payload field reference.

3. Handle Panel Opened Through Overlay

Monitor when a panel is opened through an overlay interaction:

m.lib.observeField("panelOpenedThroughOverlay", "onPanelOpenedThroughOverlay")

function onPanelOpenedThroughOverlay(event as Object)
    wasOpened = event.getData()
    if wasOpened then
        print "Panel was opened by clicking an overlay"
    end if
end function

Overlay Configuration

Overlays are configured through the Maestro backend and automatically appear based on event triggers. However, you can control some aspects:

Display QR Codes

Enable or disable QR code display in overlays:

m.lib.displayQRCodes = true  ' Enable QR codes
m.lib.displayQRCodes = false ' Disable QR codes

Best Practices

Don't Block User Interaction: Overlays should enhance the experience, not interrupt it
Test Overlay Timing: Use test overlays during development to ensure proper timing and positioning
Handle Overlay Misalignment: Double-check overlay configuration coordinates and ensure they fit within the panel's width and height

Example: Complete Overlay Integration

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

        ' Observe overlay lifecycle events
        m.lib.observeField("onOverlayEvent", "onOverlayEvent")
        m.lib.observeField("panelOpenedThroughOverlay", "onPanelOpenedThroughOverlay")

        ' Configure the SDK
        m.lib.config = {
            siteID: "your-site-id",
            eventID: "your-event-id",
            useProdEnv: true
        }

        ' Enable QR codes in overlays
        m.lib.displayQRCodes = true

        ' Set panel size
        m.lib.width = 1280
        m.lib.height = 720

        m.top.appendChild(m.lib)
    end if
end sub

function onOverlayEvent(event as Object)
    data = event.getData()
    eventType = data.type
    payload = data.payload

    if eventType = "will-appear"
        ' Grant or deny the overlay. Respond before the fallback timer fires.
        m.lib.setDataToOverlay = {
            overlayId: payload.overlayId,
            canAppear: true,
            canFocus: false
        }
    else if eventType = "did-appear"
        print "Overlay appeared: "; payload.overlayId
    else if eventType = "did-engage"
        print "Viewer engaged with overlay: "; payload.overlayId
    else if eventType = "did-dismiss"
        ' Overlay dismissed by timeout, Back key, or dismissOverlay().
        if not payload.focusRestoredBySDK
            ' Place focus in your application here if needed
        end if
    end if
end function

function onPanelOpenedThroughOverlay(event as Object)
    wasOpened = event.getData()
    if wasOpened then
        print "User clicked overlay and opened panel"
        ' You might want to track this interaction
    end if
end function

Troubleshooting

Overlays Not Appearing: Ensure your event is properly configured in the Maestro dashboard with overlay triggers.

Overlay Misaligned: Verify the panel width and height are set correctly before displaying overlays.

Test Overlays Not Working: Make sure sendTestOverlay is set with a valid value ("fantasy" or "bet") after the SDK is fully loaded.

Overlay Integration

Overview​

Integration Steps​

1. Handle Overlay Lifecycle Events​

Granting or Denying Overlay Appearance​

Back Key Dismiss​

2. Track Overlay Analytics​

Permission and focus handshake​

Focus management after dismissal​

Analytic tracking events​

2. Trigger Test Overlays​

2. Observe Overlay Analytics Callbacks​

3. Handle Panel Opened Through Overlay​

Overlay Configuration​

Display QR Codes​

Best Practices​

Example: Complete Overlay Integration​

Troubleshooting​