OptiViewAds — Roku API reference (1.2.1)

Fields

Bind and observe these SceneGraph fields on the OptiViewAds node.

Field	Type	Use	Description
`videoNode`	node	write	The application's `Video` node. Bind it before `startSession`; changing it during a session requires a new session (`ROKU-VIDEO-BINDING-CHANGED`). The SDK never sets this node's source.
`adUiNode`	node	write	The node Google IMA draws its ad UI into (for example the skip button or ad countdown).
`operationResult`	assocarray	observe	Result of an asynchronous call: `operationId`, `generation`, `status` and an optional `reason`. A `ready` result of `startSession` carries `playbackUrl`, `deliveryMode` and, in SSAI, `ssaiStream`. See Operation results.
`sdkEvent`	assocarray	observe	Ad, break and status events (see Events). Each event carries `type`, `generation` and a sequence; break events carry the break and its `occurrence`.
`diagnosticEvent`	assocarray	observe	Diagnostics with `code`, an optional `reason` and code-specific context (see Diagnostics).
`gatewayRequest`	assocarray	observe	Interception and macro requests (`kind`: `manifest-request`, `manifest-response` or `asset-parameter-macros`) with `requestId`, `generation`, `value` and `context`. Answer each with `resolveGateway` within two seconds.
`playerClockAnchor`	assocarray	write	Optional, externally verified clock anchor used only when native `Video.positionInfo` UTC is unavailable: `generation`, `source: "program-date-time"`, `verified: true`, `position` (seconds on the Video) and `pdt` (source Program Date Time, epoch seconds). Set `{ generation, invalidate: true }` to withdraw it. A rejected anchor reports `ROKU-PLAYER-CLOCK-INVALID`.

Functions

Call with CallFunc. Asynchronous calls return an operation ID and report on operationResult; getters return snapshots.

`startSession`

startSession(config as Object) as Integer

Starts a session for one channel and returns an operation ID. Results arrive on operationResult; on ready, load its playbackUrl into a ContentNode (streamFormat: "hls") on the bound Video. ready waits until the first break manifest has decided the delivery mode; if that manifest fails, the session continues content-first in SGAI. A new startSession supersedes the previous session.

Operation statuses: ready, error, cancelled

`endSession`

endSession() as Integer

Ends ad insertion. While playback is still attached it reports draining (playback-detach-required) and keeps the published stream available; stop and detach the Video, then the session reports ended.

Operation statuses: ended, draining

`destroy`

destroy() as Integer

Releases the component's workers. Refuses with playback-detach-required while the Video still uses the SDK's URL; stop and detach playback first.

Operation statuses: destroyed, error

`updateAssetParameters`

updateAssetParameters(parameters as Object) as Integer

Replaces the runtime ad tag parameters used for future breaks (merged with the start config and manifest parameters). A break already committed is not changed. Requires an active session.

Operation statuses: updated, error

`updateAssetParameterMacros`

updateAssetParameterMacros(update as Object) as Integer

Sets or removes macro values: { set: { NAME: value }, remove: ["NAME"] }. Requires an active session.

Operation statuses: updated, error

`updateRafMetadata`

updateRafMetadata(metadata as Object) as Integer

SSAI: updates the Roku Advertising Framework content metadata { contentId, contentGenre, kidsContent, contentLength }.

Operation statuses: updated, error

`getAdBreakStatus`

getAdBreakStatus() as Object

Snapshot of the break state: phase, state, generation, ticking, the selected break and its countdown, all known breaks (breakId, occurrence, state, reason, reasonDetail) and deliveryMode. When playback must be restarted it adds recoveryRequired, reloadRequired and reloadReason.

`isSessionActive`

isSessionActive() as Boolean

Whether ad insertion is starting or active. It does not report whether the Video is playing.

`getSessionInfo`

getSessionInfo() as Object

Snapshot of the session: generation, active, destroyed and, during a session, state, playbackEpoch, recoveryRequired, reloadRequired, channelId, deliveryMode, deliveryModeSource and publishedSourceEnd (UTC, ISO 8601) when available.

`getCapabilities`

getCapabilities() as Object

Describes what the installed version implements (see Capabilities). Check it instead of assuming a feature.

`resolveGateway`

resolveGateway(result as Object) as Boolean

Answers a gatewayRequest: { requestId, generation, status, value } with status "ok" or "error". Returns false for an unknown or stale request. Without an answer within two seconds the SDK uses the original request, response or registered macro values and reports a diagnostic.

Start configuration

Keys of the object passed to startSession. Built-in macros: $OPTIVIEW_USER_AGENT$ , $OPTIVIEW_PLAYER_WIDTH$ , $OPTIVIEW_PLAYER_HEIGHT$ , $OPTIVIEW_BREAK_DURATION_SECONDS$ , $OPTIVIEW_BREAK_DURATION_MS$ .

Key	Type	Description
`contentUrl` required	String	Live HLS master playlist.
`manifestUrl` required	String	Break manifest URL. Network manifests must carry a valid detached signature.
`contentHeaders`	Object	HTTP headers sent with content playlist and segment requests.
`assetParameters`	Object	Ad tag parameters added to Google Ad Manager requests, merged with the manifest's parameters.
`assetParameterMacros`	Object	Initial values for $NAME$ macros in asset parameters.
`userAgent`	String	Value of the built-in $OPTIVIEW_USER_AGENT$ macro.
`playerWidth`	Integer	Value of the built-in $OPTIVIEW_PLAYER_WIDTH$ macro.
`playerHeight`	Integer	Value of the built-in $OPTIVIEW_PLAYER_HEIGHT$ macro.
`requestInterceptor`	Boolean	Route each manifest request through `gatewayRequest` (`manifest-request`).
`responseInterceptor`	Boolean	Route each manifest response through `gatewayRequest` (`manifest-response`).
`macroResolver`	Boolean	Resolve macro values through `gatewayRequest` (`asset-parameter-macros`).
`alignmentToleranceSeconds`	Float	Allowed alignment difference between renditions and at the return to content, `0.002` to `0.250` seconds. Default `0.250`.
`mode`	String	`"sgai"` or `"ssai"`: overrides the break manifest's delivery rules (`DA-DELIVERY-MODE-OVERRIDDEN`).
`raf`	Object	SSAI: `{ contentId, contentGenre, kidsContent, contentLength }` for Roku Advertising Framework measurement.
`streamActivityMonitorId`	String	SSAI: passed to the Google DAI stream request.

Operation results

Status	Meaning
`ready`	The session is ready; the result carries `playbackUrl` and `deliveryMode`.
`error`	The call failed; `reason` names why (for example `missing-session-url`, `invalid-configuration`, `invalid-video-binding`, `invalid-alignment-tolerance`, `invalid-delivery-mode`, `invalid-raf-metadata`, `invalid-stream-activity-monitor-id`, `invalid-parameters`, `invalid-macros`, `playback-detach-required`, `unsupported-state`, `no-session`, `destroyed`).
`cancelled`	Superseded by a newer call or ended with the session (`superseded`, `session-ended`).
`draining`	`endSession` while playback is attached; detach to finish.
`ended`	The session ended.
`destroyed`	The component released its workers.
`updated`	A parameter, macro or RAF update was applied.

Events

Delivered on sdkEvent. Tracking events come only from genuine IMA callbacks.

Type	Meaning
`adbreakbegin`	A break started playing at its actual splice point.
`adbegin`	An ad in the pod started (from a genuine IMA callback).
`adfirstquartile`	First quartile of the current ad.
`admidpoint`	Midpoint of the current ad.
`adthirdquartile`	Third quartile of the current ad.
`adend`	The current ad completed.
`adbreakend`	The break completed.
`aderror`	An ad or break failed. A failure after publication also sets `recoveryRequired`; start a new session.
`adbreakskipped`	A break was refused before anything was shown and content kept playing. `reason`: `late`, `not-ready`, `preparation-failed`, `unsupported`, `overlap`, `start-delay`, `removed`, `insufficient-remaining` or `resource-limit`; `reasonDetail` names the specific cause, with `podEvidence` or `preparationEvidence` where available.
`adbreakstatus`	Break state and countdown updates (same shape as `getAdBreakStatus`).
`adchannelchange`	The break manifest moved to another ads channel; carries `previousChannelId`, `channelId`, `previousDeliveryMode` and `deliveryMode`.
`playbackreloadrequired`	Playback must be restarted in a new session (for example `delivery-mode-changed`, `ssai-stream-changed`, or a viewer seek that fenced tracking).
`adinteractiveexit`	SSAI: the viewer left a Roku Advertising Framework interactive ad; stop playback and restore focus.

Diagnostics

Delivered on diagnosticEvent.

Roku-only codes

Code	Meaning
`ROKU-BREAK-START-SHIFTED`	A break's start moved to a segment boundary. `reason` (`earlier`/`later`), signed `shiftSeconds`, `requestedStart`, `spliceStart`.
`ROKU-RESUME-SHIFTED`	The return to content moved content by more than 1 ms. `reason` (`delayed`/`advanced`), signed `shiftSeconds`, `nearestBoundary`.
`ROKU-BREAK-HELD`	Publication waited for a pod that was still preparing. `reason` (`pod-ready`/`skipped`), `heldSeconds`.
`ROKU-PREPARATION-RETRY`	A failed pod download is being retried. `reason`, `attempt`.
`ROKU-PREPARATION-FAILED`	A pod could not be prepared; the break is skipped, or ends if it was already published. `reason` and optional evidence.
`ROKU-MEDIA-FAILED`	Content or ad publication failed. Before startup completes it fails the start; after publication it ends playback.
`ROKU-PUBLICATION-FAILED`	The local playlist snapshot was invalid.
`ROKU-PROXY-ERROR`	The local HLS proxy failed or did not stop in time.
`ROKU-SOURCE-EVIDENCE`	Informational: content verification is waiting for evidence (for example a slow segment). Playback continues.
`ROKU-MANIFEST-FAILED`	A break manifest request failed.
`ROKU-MANIFEST-INVALID`	A break manifest failed validation; it is not used and is polled again after 5 s.
`ROKU-MANIFEST-UNSUPPORTED`	The manifest cannot be used for Roku insertion (for example its timebase is not `wallclock`).
`ROKU-POLLING-INVALID`	The manifest's polling instructions were invalid; the manifest is polled again after 5 s.
`ROKU-RESOURCE-LIMIT`	Too many breaks: a manifest over the limit is not used; a full session ledger stops ad insertion for the session.
`ROKU-IMA-FAILED`	IMA pod serving could not be set up; it is retried after 10 s and breaks due meanwhile are skipped.
`ROKU-IMA-STOP-TIMEOUT`	The IMA pod-serving task did not stop in time during cleanup.
`ROKU-DAI-STOP-TIMEOUT`	SSAI: the IMA DAI task did not stop in time during cleanup.
`ROKU-PARAMETERS-FAILED`	Updating the ad tag parameters failed or timed out; the break is skipped.
`ROKU-SSAI-PARAMETERS-FAILED`	SSAI: updating the DAI ad tag parameters failed or timed out.
`ROKU-SSAI-CLIENT-BREAKS-IGNORED`	SSAI: event-triggered manifest breaks are not rendered.
`ROKU-MACRO-FAILED`	The application's macro resolver failed or timed out; registered values are used.
`ROKU-PLAYER-CLOCK-INVALID`	A supplied `playerClockAnchor` was rejected; it needs a verified source Program Date Time.
`ROKU-PLAYBACK-EPOCH-CHANGED`	Playback jumped (for example a viewer seek); old tracking is fenced and a reload is required.
`ROKU-VIDEO-BINDING-CHANGED`	`videoNode` changed during a session; start a new session.

Shared codes emitted on Roku

Code	Level	Meaning
`DA-MANIFEST-POLLED`	info	A manifest poll refresh succeeded (cadence follows the manifest polling config).
`DA-MANIFEST-CHANNEL-CHANGED`	info	A polled manifest describes a different ads channel (channelId, GAM identity or timebase changed); the SDK re-aligned its ad setup and resolved delivery mode again while the session and content playback continued. context: previousChannelId, channelId, reason, manifestUrl.
`DA-MANIFEST-INTERCEPT-FAILED`	warn	The customer manifest-response interceptor threw; the un-modified parsed manifest was used instead.
`DA-MANIFEST-REQUEST-INTERCEPT-FAILED`	warn	The customer manifest-request interceptor threw; the normal network fetch of the original URL was used instead.
`DA-DELIVERY-MODE-RESOLVED`	info	Delivery mode (sgai/ssai) resolved for the session at start and again on an ads-channel switch from the manifest's delivery rules (or the explicit client config), with the detected device profile.
`DA-DELIVERY-MODE-UNKNOWN`	warn	The matching delivery rule carried an unrecognized mode value; sgai is used (forward compatibility).
`DA-DELIVERY-MODE-OVERRIDDEN`	info	The manifest's delivery rules resolved a different mode, but the explicit client config takes precedence.
`DA-DELIVERY-MODE-CHANGE-IGNORED`	warn	An ordinary manifest poll resolves a different delivery mode; the mode pinned for the session stays in force. An ads-channel switch resolves the mode again.
`DA-GAM-CONFIG-MISSING`	error	The break manifest carries no usable "gam" vendorConfiguration entry; GAM assets are skipped.
`DA-GAM-START-DEFERRED`	info	The SGAI IMA stream request is deferred until the configured ad start delay has been played; context includes adStartDelaySec.
`DA-ASSET-PARAMETERS-UPDATED`	info	The break manifest's session-level asset parameters changed; the merged parameters were pushed to the active GAM stream. context: source ('manifest'), keys (parameter names only, never values).
`DA-ASSET-MACRO-UNKNOWN`	warn	An asset parameter value contained a macro the SDK has no value for (an unknown or unavailable OptiView macro, or a registered customer macro that returned no value); the parameter was still sent, with the macro kept as its literal token. Raised once per parameter key and macro. context: key, macro, breakId, assetId.
`DA-SSAI-UNAVAILABLE`	error	The manifest selected ssai delivery but no vendor configuration can provide a stitched stream (no gam entry with an assetKey); at start the session fails, while on a channel switch the session stays in sgai.
`DA-SSAI-SESSION-FAILED`	error	The SSAI session failed to start (IMA stream init, stream id, or stitched-stream load).
`DA-SSAI-IMA-ERROR`	error	IMA reported an error during the SSAI stream session.
`DA-BREAK-ABANDONED`	warn	A break was still in flight when the session was torn down (endSession, destroy, or a startSession over an active session). context: breakId, cause, phase, unbalancedAdBegin, adIndex, totalAds, assetId.
`DA-TARGETING-FIELD-UNKNOWN`	warn	A targeting field is not recognized and the targeted entry does not match.
`DA-TARGETING-INVALID`	warn	A targeting constraint is malformed or incomplete and the targeted entry does not match.
`DA-TARGETING-VALUE-UNKNOWN`	warn	A targeting value is not recognized and the targeted entry does not match.

Capabilities

Returned by getCapabilities() for this version.

Key	Value	Meaning
`deliveryModes`	`["sgai", "ssai"]`	Supported delivery modes.
`ssaiVendor`	`"gam-dai-full-service"`	SSAI vendor integration.
`ssaiStreamTypes`	`["live"]`	SSAI stream types.
`ssaiFormats`	`["hls"]`	SSAI stream formats.
`ssaiClientBreaks`	`false`	Whether event-triggered manifest breaks render in SSAI.
`rafMeasurement`	`true`	Roku Advertising Framework measurement in SSAI.
`rafInteractiveAds`	`true`	Roku Advertising Framework interactive ads in SSAI.
`readyAwaitsDeliveryMode`	`true`	`ready` waits for the first manifest to decide the delivery mode.
`timebase`	`"wallclock"`	Break manifest timebase supported for insertion.
`sourceProgramDateTimeRequired`	`true`	SGAI needs `EXT-X-PROGRAM-DATE-TIME` on the content.
`insertionMode`	`"replace"`	Ads replace content for their duration.
`appOwnedVideo`	`true`	The application owns the `Video` node.
`signedManifests`	`true`	Network break manifests must be signed.
`clearMuxedTs`	`true`	Clear muxed MPEG-TS content.
`cmaf`	`true`	CMAF (fMP4) content and ads.
`demuxed`	`true`	Separate audio and video renditions.
`abr`	`true`	Adaptive bitrate across several renditions.
`maxRenditions`	`8`	Maximum number of renditions stitched together.
`compatibleTopologyRequired`	`true`	Ad renditions must be compatible with the content.
`drm`	`false`	Encrypted content.
`lowLatencyParts`	`false`	Low-latency HLS parts.
`sourceHoldBack`	`true`	Publication honours the stream's `HOLD-BACK`.
`unalignedBreakStart`	`"nearest-segment-boundary"`	How a break start between segment boundaries is handled.
`sourceChangesAtBreaks`	`false`	Whether the Video source changes at ad boundaries.
`shutdownRequiresDetachedPlayback`	`true`	Playback must be detached before `destroy`.
`nativeUtcClock`	`true`	Native `Video.positionInfo` UTC is used as the player clock.
`externalClockAnchorSupported`	`true`	`playerClockAnchor` is accepted as a fallback.
`initialTuneInPolicy`	`"content-until-prepared"`	Content plays first; ads join once prepared.
`lateOpportunityPolicy`	`"skip"`	Breaks already exposed without a ready pod are skipped.
`alignmentToleranceSeconds`	`0.250`	Default `alignmentToleranceSeconds`.
`supportedAlignmentToleranceSeconds`	`[0.002, 0.250]`	Accepted range of `alignmentToleranceSeconds`.