setDataToOverlay

Client action field used to grant or deny an overlay's request to appear, and to control whether it takes Roku focus.

Description

When the SDK is about to display an overlay, it emits a will-appear event via onOverlayEvent. Your application responds by setting setDataToOverlay with the grant/deny decision for that specific overlay.

If your application does not respond within approximately 100 ms, the SDK proceeds with the default permissions included in the will-appear payload.

Type

assocArray

Fields

Field	Type	Required	Description
overlayId	string	Yes	Identifies the overlay to respond to. Must match payload.overlayId from the will-appear event.
canAppear	boolean	No	true to allow the overlay to appear; false to skip it. Defaults to the value in the will-appear payload.
canFocus	boolean	No	true to allow the overlay to take Roku focus; false to prevent it. Defaults to the value in the will-appear payload.

Usage

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

function onOverlayEvent(event as Object)
    overlayEvent = event.getData()

    if overlayEvent.type = "will-appear"
        payload = overlayEvent.payload

        ' Allow the overlay but prevent it from stealing focus
        m.lib.setDataToOverlay = {
            overlayId: payload.overlayId
            canAppear: true
            canFocus: false
        }
    end if
end function

Example — blocking an overlay during a critical moment

function onOverlayEvent(event as Object)
    overlayEvent = event.getData()

    if overlayEvent.type = "will-appear"
        payload = overlayEvent.payload

        ' Suppress overlays while a dialog is on screen
        m.lib.setDataToOverlay = {
            overlayId: payload.overlayId
            canAppear: not m.dialogIsOpen
            canFocus: false
        }
    end if
end function

Notes

• Only respond to will-appear events. Responses to other lifecycle event types are ignored.
• The overlayId must match exactly — responses for unknown or already-resolved IDs are silently discarded.
• Omitting canAppear or canFocus falls back to the default values sent in the will-appear payload.
• Setting canAppear: false skips the overlay entirely; the SDK moves on to the next queued overlay.

Related

• onOverlayEvent — Observable field that emits lifecycle events, including the will-appear event this field responds to.
• Overlay Integration Guide