Roku SDK API Reference

This page documents the public API of the StreamLayer Roku SDK. The SDK is delivered as a SceneGraph node (StreamLayer) that you add to your scene. All methods are invoked with callFunc on that node, and state is read back through observable fields.

For setup instructions, see the Integration Guide. For version history, see the Changelog.

' The SDK node, created from the SceneGraph component
m.streamLayer = m.top.createChild("StreamLayer")

Invocation pattern

Every method below is called through the node, for example:
m.streamLayer.callFunc("setEvent", "nba-lakers-2026-05-28"). Calling a method
that is not available in the current SDK mode is a safe no-op — it is logged,
not thrown.

Table of Contents

• Initialization & Lifecycle
• Playback & Pause Ads
• Overlay & Focus
• Observable Fields

Initialization & Lifecycle

initSdk

function initSdk(params as object) as boolean

Initializes the SDK: configures logging, analytics, and ad modes, validates the optional player reference, loads configuration, and starts the SceneGraph runtime. Call this once before any other method.

Returns: boolean — true when parameters are accepted and initialization starts; false when params is missing.

Example:

success = m.streamLayer.callFunc("initSdk", {
    apiKey: "your-sdk-api-key"
    apiUrl: "https://api.streamlayer.io"
    playerRef: m.videoPlayer
    isLoggingEnabled: true
    isAnalyticsEnabled: true
    isVastModeEnabled: false
})
' success = true → the StreamLayer Element runtime is initializing

attachPlayer

sub attachPlayer(ref as object)

Attaches (or replaces) the host video player after initialization. The reference must be an roSGNode that exposes control and state fields; otherwise it is rejected with a warning and ignored.

Example:

m.streamLayer.callFunc("attachPlayer", m.videoPlayer)

setEvent

sub setEvent(hostEventId as string)

Binds the SDK to a host event so the StreamLayer Element starts receiving interactive content for it. The player must be attached first.

Example:

m.streamLayer.callFunc("setEvent", "nba-lakers-2026-05-28")

getVersion

function getVersion() as object

Returns the running SDK version and product name.

Returns: object with:

Example:

info = m.streamLayer.callFunc("getVersion")
print info.name + " v" + info.version
' StreamLayer Roku SDK v2.8.0-001

Playback & Pause Ads

setPauseState

sub setPauseState(pauseState as boolean)

Notifies the SDK that the host player's pause state changed. While a promo or notification is visible, the call is ignored. Pausing also cancels any scheduled overlay.

Example:

m.streamLayer.callFunc("setPauseState", true)

showPauseAd

sub showPauseAd(params = invalid)

Requests a pause ad unit for the current event. In VAST mode you must pass a params object containing the creative URL; in full mode the SDK loads its own pause ad units and the argument is optional. The call is ignored if no event is set.

Example:

' VAST mode
m.streamLayer.callFunc("showPauseAd", { vastUrl: "https://ads.example.com/vast.xml" })

' Full mode
m.streamLayer.callFunc("showPauseAd")

closePauseAd

sub closePauseAd()

Closes the active pause ad unit. Routes to the external (VAST) or internal close path depending on the current mode.

Example:

m.streamLayer.callFunc("closePauseAd")

setVastModeEnabled

sub setVastModeEnabled(enabled as boolean)

Switches the SDK between full mode and VAST mode at runtime. No-ops if the mode is already set.

Example:

m.streamLayer.callFunc("setVastModeEnabled", true)

resumeRequested

sub resumeRequested()

Signals that playback should resume — typically from the pause ad unit's Play button. Sets the observable isResumeRequested field to true so the host can resume its player.

Example:

m.streamLayer.callFunc("resumeRequested")

Overlay & Focus

closeOverlay

sub closeOverlay()

Closes all active StreamLayer Element overlays and any open pause ad unit, cancels any scheduled overlay, and resets the promo and notification visibility flags.

Example:

m.streamLayer.callFunc("closeOverlay")

setFocus

sub setFocus(value)

Forwards focus to whichever surface is currently visible — the promo, notification, or pause ad presenter.

Example:

m.streamLayer.callFunc("setFocus", true)

Observable Fields

Read these fields, or observe them with observeField, to react to SDK state. All are set by the SDK; the host observes them.

Example:

m.streamLayer.observeField("isResumeRequested", "onResumeRequested")

sub onResumeRequested(event as object)
    if event.getData() = true then m.videoPlayer.control = "resume"
end sub