onOverlayEvent

Observable field that emits overlay lifecycle events as overlays appear, are engaged, and are dismissed.

Description

The SDK fires onOverlayEvent at four points in every overlay's lifecycle. Observing this field lets your application know when an overlay is about to appear (and grant or deny it), when it has appeared, when a viewer engages with it, and when it is dismissed.

The most important event is will-appear, which opens a brief window for your application to approve or block the overlay — and to control whether it takes focus — by responding with setDataToOverlay.

Type

assocArray

Payload

Every event shares a common top-level shape:

Field	Type	Description
`type`	`string`	Lifecycle event type. One of `"will-appear"`, `"did-appear"`, `"did-engage"`, `"did-dismiss"`.
`payload.overlayId`	`string`	Unique identifier for this overlay instance.
`payload.associatedPanel`	`string`	The panel this overlay is associated with.

`will-appear` — additional payload fields

Field	Type	Description
`payload.canAppear`	`boolean`	Default permission for the overlay to appear.
`payload.canFocus`	`boolean`	Default permission for the overlay to take Roku focus.

Respond to this event via setDataToOverlay. If your application does not respond within approximately 100 ms, the SDK proceeds using these default values.

`did-dismiss` — additional payload field

Field	Type	Description
`payload.focusRestoredBySDK`	`boolean`	`true` if the SDK already restored focus to its prior position. `false` if the client is responsible for placing focus.

Usage

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

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

    if eventType = "will-appear"
        ' Grant the overlay but prevent it from stealing focus
        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"
        if not payload.focusRestoredBySDK
            ' The overlay held focus and the SDK could not restore it —
            ' return focus to the appropriate element in your app.
            m.videoPlayer.setFocus(true)
        end if
    end if
end function

Lifecycle

Event	When it fires	Client action
`will-appear`	Before the overlay is rendered	Respond via `setDataToOverlay` to grant or deny. No response within ~100 ms means the SDK proceeds with the payload defaults.
`did-appear`	After the overlay is rendered and focused (if focus was granted)	Optional — use for analytics or UI adjustments.
`did-engage`	When the viewer presses OK on a focused overlay	Optional — the SDK navigates to the associated panel automatically.
`did-dismiss`	After the overlay times out or auto-dismisses	Check `focusRestoredBySDK` to decide whether to restore focus.

Notes

will-appear is the only event that accepts a client response. All other events are informational.
If your application does not observe onOverlayEvent, overlays appear with the SDK's default permissions.
When focusRestoredBySDK is true in a did-dismiss payload, do not move focus — the SDK has already restored it to the prior panel position.
Responding to will-appear with canAppear: false skips the overlay entirely; the SDK moves on to the next queued overlay.

setDataToOverlay — Respond to will-appear events to control overlay display and focus.
Overlay Integration Guide
panelOpenedThroughOverlay

onOverlayEvent

Description​

Type​

Payload​

will-appear — additional payload fields​

did-dismiss — additional payload field​

Usage​

Lifecycle​

Notes​

Related​