Fields
SceneGraph fields on the OptiViewAds node: inputs the application binds, plus the read-only events constants.
| 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). |
events | assocarray | read | Event type constants for addEventListener, keyed by name: m.ads.events.adbreakbegin is "adbreakbegin" (see Events). |
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 through operationresult events; getters return snapshots. Register listeners with addEventListener(eventType, listenerOwner, listenerName): the owner is the application's node and the listener one of its interface functions, invoked with the event as its argument.
addEventListener
addEventListener(eventType as String, listenerOwner as Object, listenerName as String)
Subscribes listenerOwner.listenerName to an event type (see Events). listenerOwner is the application's node (usually m.top) and listenerName one of its interface <function>s, invoked with the event as its single argument: m.ads.callFunc("addEventListener", m.ads.events.adbreakbegin, m.top, "onAdBreakBegin"). A listener that fails when called is dropped for that event type with one warning; the other listeners still get the event.
removeEventListener
removeEventListener(eventType as String, listenerOwner as Object, listenerName as String)
Removes a listener added with addEventListener (same event type, owner and function name). Unknown listeners are ignored.
startSession
startSession(config as Object) as Integer
Starts a session for one channel and returns an operation ID. Results arrive as operationresult events; 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.
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.
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. Listeners stay registered so later calls still report error (destroyed).
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.
updateAssetParameterMacros
updateAssetParameterMacros(update as Object) as Integer
Sets or removes macro values, keyed by the full token including both $ delimiters: { set: { "$NAME$": value }, remove: ["$NAME$"] }. An empty string or invalid value omits the parameters that use the macro. Requires an active session.
updateRafMetadata
updateRafMetadata(metadata as Object) as Integer
SSAI: updates the Roku Advertising Framework content metadata { contentId, contentGenre, kidsContent, contentLength }.
getAdBreakStatus
getAdBreakStatus() as Object
Snapshot of the break state: phase, state, generation, ticking, the selected break and its countdown, the breaks the manifest lists plus breaks that ended less than 30 s ago (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, eventId when an event applies, 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 event: { 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. A manifest supplied as a BrightScript object is read like the same manifest sent as JSON: manifest fields match their spec spelling whatever case the object stores, while free-form keys keep the case the object stores.
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. With OptiViewAdsInterceptor and the OptiView Player's THEOlive source, pass the THEOlive channel ID instead: a value that is not an http(s) URL declares an SSAI-only session (nothing is stitched; the start fails with content-url-required if the break manifest selects SGAI). A session the interceptor starts after configure gets the discovered SGAI endpoint as its contentUrl. |
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 macros in asset parameters, keyed by the full token: { "$SEGMENT$": "sports" }. An empty string or invalid value omits the parameters that use the macro. |
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 a gatewayrequest event (manifest-request). |
responseInterceptor | Boolean | Route each manifest response through a gatewayrequest event (manifest-response). |
macroResolver | Boolean | Resolve macro values through a gatewayrequest event (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, contentUrl 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, content-url-required, 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
Event types for addEventListener. Every event carries type and generation; ad, break, status and diagnostic events also carry a sequence, operationresult an operationId and gatewayrequest a requestId. Tracking events come only from genuine IMA callbacks.
| Type | Meaning |
|---|---|
operationresult | Result of an asynchronous call: operationId, operation (startSession, endSession, destroy, updateAssetParameters, updateAssetParameterMacros, updateRafMetadata), generation, status and an optional reason. A ready result of startSession carries playbackUrl, contentUrl, deliveryMode and, in SSAI, ssaiStream. See Operation results. |
diagnostic | Diagnostics with code, an optional reason and code-specific context (see Diagnostics). |
gatewayrequest | 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. |
adbreakbegin | A break started playing at its actual splice point. Break and ad events carry eventId when the break belongs to a channel event. |
adbegin | An ad in the pod started (from a genuine IMA callback). Event-scoped ads carry eventId. |
adfirstquartile | First quartile of the current ad. Event-scoped ads carry eventId. |
admidpoint | Midpoint of the current ad. Event-scoped ads carry eventId. |
adthirdquartile | Third quartile of the current ad. Event-scoped ads carry eventId. |
adend | The current ad completed. Event-scoped ads carry eventId. |
adtimeupdate | Emitted once per 0.25-second pulse while the ad progresses, not while paused, stalled or seeking. currentTime and duration are seconds; SGAI uses the manifest pod asset, while SSAI uses the current ad asset and includes deliveryMode: "ssai". timestamp is epoch milliseconds with millisecond precision. |
adbreakend | The break completed. Event-scoped breaks carry eventId. |
aderror | An ad or break failed. Break and ad events carry eventId when applicable. 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, including event-boundary-preparation for a newly announced current-configuration break in an event lookahead window, with podEvidence or preparationEvidence where available. Event-scoped breaks carry eventId. |
adbreakstatus | Break state and countdown updates (same shape as getAdBreakStatus). |
adchannelchange | The break manifest moved to another ads channel or crossed an event boundary. Carries previousChannelId, channelId, reason (channel-id-added, channel-id-changed, channel-id-removed, vendor-configuration-changed, timebase-changed or event-boundary), manifestUrl, previousDeliveryMode, deliveryMode and always eventId (string or invalid when leaving an event). Wallclock event configuration applies at [start, end) boundaries. Same-event manifest updates use ordinary update handling; event-boundary is reserved for an active event ID change. SGAI event timing follows playback PDT and holds the last known position while PDT is unavailable. For SGAI, OptiView Ads may prepare the next event's GAM/IMA session up to 30 seconds early when no unfinished current-configuration break starts before the boundary; event ID, adchannelchange, getSessionInfo(), ad-start delay and delivery switch only at the boundary. Newly announced current-configuration breaks in that window are skipped with reason: "not-ready" and reasonDetail: "event-boundary-preparation". SSAI event timing uses the device clock because Roku's DAI stream does not provide source PDT; an event switch during a stitched break waits for break end or until the break's duration plus 30 seconds has elapsed. |
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 as diagnostic events with code and an optional reason.
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; more than 512 breaks listed or in progress at once 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-EVENT-INVALID | warn | A channel event was ignored because its time window or configuration is invalid, or because events are unsupported for the manifest timebase. context: eventId and index when available. |
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/ssb) 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; context.source is external-playback or external-playback-ended when AirPlay switched the session to the SSB stream and back. |
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. |
Other components
Further public components of the OptiViewAds library. Only the fields and functions listed are for application use; their other interface functions are called by the player.
OptiViewAds:OptiViewAdsSDKIntegration
Custom ad integration for the OptiView Player (THEOplayer Roku SDK). Register it with the player and the player's ads API dispatches the Ads SDK's break and ad events (adloaded, adbreakbegin, adimpression, adbegin, the quartiles, adend, adbreakend, aderror) with player.ads.playing, currentAdBreak and currentAds kept in step, so channels and analytics connectors that already listen on player.ads need no second event source. The Ads SDK itself keeps emitting its own events.
integration = createObject("roSGNode", "OptiViewAds:OptiViewAdsSDKIntegration")
integration.adsSdk = ads ' the OptiViewAds node
player.ads.callFunc("registerServerSideIntegration", integration.integrationKind, integration)
' On the "ready" result of startSession:
player.source = { sources: [{ src: result.playbackUrl, type: "application/x-mpegurl", ssai: { integration: integration.integrationKind } }], live: true }
- The player only starts registered integrations for sources that carry an ad description: the source must set
ssai: { integration: integration.integrationKind }. The integration accepts the source once the Ads SDK session is active (startSessionsucceeded and the session was not ended or destroyed). - Register it once per player.
player.callFunc("destroy")tears it down; destroy theOptiViewAdsnode afterwards. - Do not call the node's functions: they implement the player's ad integration contract and are invoked by the player. The player prints
There was an issue scheduling the ad.once per source because the integration has nothing to schedule in the Roku Ads Framework.
| Field | Type | Use | Description |
|---|---|---|---|
adsSdk | node | write | The OptiViewAds node whose events the player should dispatch. Bind it before registering the integration; set to invalid to detach. |
integrationKind | string | read | The integration kind, optiview-ads-sdk: pass it to registerServerSideIntegration and set it as ssai.integration on the source the player plays. |
OptiViewAds:OptiViewAdsInterceptor
THEOlive discovery response interceptor for the OptiView Player (THEOplayer Roku SDK). It rewrites the distribution the player discovers so the stream of the Ads SDK session becomes the only priority-0 endpoint (src the stream URL, srcType: "hls", adSystem: "none", provider: "external", weight: 100): the Google DAI stream in SSAI, the SDK's stitched stream (its local proxy URL) in SGAI. In SSAI the DAI endpoint of the session's asset key is removed (V2 and V3 discovery shapes). In SGAI the endpoint the SDK stitches is removed: on V3 the adSystem: "sgai" endpoint with an http(s) src and the lowest priority number, then the highest weight, then the first listed; on V2 the endpoint whose hlsSrc is the session's contentUrl (daiAssetKey and all: the player derives a DAI endpoint from it), or the stream is added in front of the others when none matches; a distribution without one (a V2 distribution without a contentUrl or without endpoints) passes through unchanged. Every endpoint that stays moves down one priority, keeping its order as fallback. Without a ready session, or for a distribution without endpoints, the response passes through exactly as fetched. After configure, with a player that supports asynchronous interceptors, it also starts the session itself from the ads.adsManifestUrl of each discovery response.
interceptor = createObject("roSGNode", "OptiViewAds:OptiViewAdsInterceptor")
interceptor.adsSdk = ads ' the OptiViewAds node
player.theoLive.discoveryResponseInterceptor = interceptor
' Session from the discovery response (ads.adsManifestUrl): the startSession config without manifestUrl.
interceptor.callFunc("configure", { assetParameters: { iu: "/network/unit" } })
player.source = { sources: [{ src: theoLiveChannelId, type: "theolive", ssai: { integration: integration.integrationKind } }] }
' Or, app-started session with a known break manifest URL (no configure call):
ads.callFunc("startSession", { contentUrl: theoLiveChannelId, manifestUrl: breakManifestUrl })
' On the "ready" result of startSession:
player.source = { sources: [{ src: theoLiveChannelId, type: "theolive", ssai: { integration: integration.integrationKind } }] }
- After
configure(config), each discovery response carryingads.adsManifestUrlmakes the interceptor returninvalidto the player and callstartSessionwithconfigplusmanifestUrl(a configuredmanifestUrlwins) and, unless configured,contentUrl: thesrcof the discoveredsgaiendpoint, so the break manifest can select SGAI or SSAI, else the distribution id (or"theolive"when absent; an SSAI-only session), not the channel ID used in app-started mode; when that start settles it writes the rewritten response (ready) or{"error": "..."}(failed or superseded; the player keeps the discovered channel) todiscoveryResponse. A response withoutads.adsManifestUrlpasses through unchanged and ends a session the interceptor started; a rediscovery of the same distribution with the same URL reuses the running session, a different URL restarts it, and another distribution (channel switch) ends the interceptor-started session before starting one for it (passing through unchanged when the SDK refuses the start while the previous stream is still attached). Requires an OptiView Player that setsplayerSupportsAsync; otherwise, and withoutconfigure, the interceptor answers synchronously. - Bind
adsSdkbefore callingstartSession: the interceptor learns the stream from thestartSessionreadyresult (playbackUrlanddeliveryMode; in SSAI alsossaiStream.assetKey, in SGAI alsocontentUrl) and forgets it when the start fails, is superseded, or the session ends or is destroyed. - In app-started mode only, pass the THEOlive channel ID as
contentUrlso the Ads SDK does not stitch content before the delivery mode is known; the player resolves the content through discovery. A channel-IDcontentUrlsession is SSAI-only; an app-started SGAI session with a URLcontentUrlreplaces the V2 endpoint with thathlsSrc(thereadyresult carries thecontentUrl; the running session's URL wins over a configured one), and for an interceptor-started SGAI session useconfigure. - Set
player.theoLive.discoveryResponseInterceptor = invalidandinterceptor.adsSdk = invalidwhen tearing the player down. - Do not call the node's other functions or write its other fields:
onDiscoveryResponseis invoked andplayerSupportsAsyncwritten by the player,onAdsOperationis invoked by the Ads SDK anddiscoveryResponseis the interceptor's answer to the player. - Do not mix modes: after
configure, do not callstartSessionyourself; the next discovery replaces that session. - While a start is in progress, only the latest pending
onDiscoveryResponsecall is answered; there is no request id. Earlier calls are left to the player's fixed 10 s timeout. After that timeout discovery continues with the original response and a laterdiscoveryResponsewrite is ignored. configure(invalid)(or any non-object) disables discovery-started sessions and ends a session the interceptor started. RebindingadsSdkends that session on the previous node before resetting discovery state. Neither ends an app-started session.
| Field | Type | Use | Description |
|---|---|---|---|
adsSdk | node | write | The OptiViewAds node whose session stream the discovery response should carry. Bind it before startSession; set to invalid to detach. |
playerSupportsAsync | boolean | read | Set to true by an OptiView Player that waits for asynchronous interceptor answers; required for configure-driven sessions. |
discoveryResponse | string | read | The asynchronous answer the interceptor writes for the player: the rewritten discovery response or a JSON object with an error property. |
configure
configure(config as Object)
Lets the interceptor start the session from the discovered ads manifest URL. config is the startSession config without manifestUrl (a given manifestUrl wins over discovery; a given contentUrl wins over the discovered SGAI endpoint and the distribution id). Call before setting the THEOlive source; pass a non-object to stop starting sessions and end any session the interceptor started.