Class: shaka.ads.InterstitialAdManager

Constructor

new InterstitialAdManager(adContainer, player, onEvent)

Parameters:
Name Type Description
adContainer HTMLElement
player shaka.Player
onEvent function
Implements:
Source:

Members

PLAYOUT_LIMIT_TOLERANCE_ :number

Extra time, in seconds, given to an ad that is being limited by its playout limit before it is cut. The limit timer runs on wall-clock time, so without it an ad whose duration is exactly its playout limit would always be cut a few frames before its own end.
Type:
  • number
Source:

adContainer_ :HTMLElement

Type:
  • HTMLElement
Source:

adEventManager_ :shaka.util.EventManager

Type:
Source:

adVideo_ :HTMLMediaElement

Type:
Source:

assetStartOffsets_ :Map<string, number>

Stores the intra-asset seek offset for interstitials that start mid-asset due to _HLS_start_offset. Maps interstitial ID to the number of seconds to seek into that asset.
Type:
  • Map<string, number>
Source:

basePlayer_ :shaka.Player

Type:
Source:

baseVideo_ :HTMLMediaElement

Type:
Source:

baseVideo_ :HTMLVideoElement

Type:
  • HTMLVideoElement
Source:

baseVideo_ :HTMLVideoElement

Type:
  • HTMLVideoElement
Source:

config_ :shaka.extern.AdsConfiguration

Type:
Source:

eventManager_ :shaka.util.EventManager

Type:
Source:

hlsMetadataIds_ :Set<string>

Type:
  • Set<string>
Source:

interstitialIds_ :Set<string>

Type:
  • Set<string>
Source:

interstitials_ :Set<shaka.extern.AdInterstitial>

Type:
Source:

isEnded_ :boolean

Type:
  • boolean
Source:

lastAdCompleteTime_ :number

Wall-clock time (ms) when the last SGAI interstitial ad break finished playing. Used to enforce the interstitialCooldown config.
Type:
  • number
Source:

lastOnSkip_ :?function()

Type:
  • ?function()
Source:

lastPlayedAd_ :shaka.extern.AdInterstitial

Type:
Source:

lastTime_ :number

Type:
  • number
Source:

onEvent_ :function(!shaka.util.FakeEvent)

Type:
  • function(!shaka.util.FakeEvent)
Source:

player_ :shaka.Player

Type:
Source:

playingAd_ :boolean

Type:
  • boolean
Source:

playingAdStartTime_ :number

Wall-clock time (ms) when the current ad break started playing. Used to re-arm the playout-limit timer when a live EXT-X-DATERANGE update shortens an interstitial that is already playing.
Type:
  • number
Source:

playoutLimitTimer_ :shaka.util.Timer

Type:
Source:

pollTimer_ :shaka.util.Timer

Type:
Source:

preloadOffsets_ :Map<string, number>

HLS preload hints (RFC 8216bis Appendix F): maps the target Date Range ID to the start time of its "com.apple.hls.preload" Date Range, which tells us how early the target's resources may be resolved.
Type:
  • Map<string, number>
Source:

preloadOnDomElements_ :Map<shaka.extern.AdInterstitial, !Array<!HTMLLinkElement>>

Type:
Source:

preloadTasks_ :Map<shaka.extern.AdInterstitial, shaka.ads.InterstitialPreloadTask>

Type:
Source:

sessionId_ :string

Type:
  • string
Source:

sortedInterstitials_ :Array<shaka.extern.AdInterstitial>

Cache of interstitials_ sorted by descending start time, invalidated (set to null) whenever interstitials_ changes. Avoids re-sorting on every getCurrentInterstitial_ call (which runs per frame).
Type:
Source:

timeUpdateTimer_ :shaka.util.Timer

Type:
Source:

unresolvedAssetLists_ :Set<shaka.ads.InterstitialAdManager.AssetListDescriptor>

Asset lists (HLS X-ASSET-LIST) whose resolution has been deferred until playback approaches them. This avoids resolving every ad decision at parse time, which would otherwise create a burst of concurrent requests. See https://github.com/shaka-project/shaka-player/issues/10191
Type:
Source:

usingBaseVideo_ :boolean

Type:
  • boolean
Source:

usingListeners_ :boolean

Type:
  • boolean
Source:

video_ :HTMLMediaElement

Type:
Source:

video_ :HTMLElement

Type:
  • HTMLElement
Source:

videoCallbackId_ :number

Type:
  • number
Source:

videoFrameCallbackHandler_ :shaka.util.VideoFrameCallbackHandler

Type:
Source:

Methods

isSafeClickThroughUri_(uri) → {boolean}

Returns true if a click-through URI is safe to hand to window.open(). Click-through URIs come from manifests and ad decision responses, which are not trusted input. window.open() with a javascript: URI executes in the opener's origin, so restrict click-throughs to http(s). Control characters and whitespace are stripped before the scheme is read, because browsers ignore them when resolving the scheme of a URL. A URI with no scheme is relative and resolves against the page, so it is allowed.
Parameters:
Name Type Description
uri string
Source:
Returns:
Type
boolean

addAdUrlInterstitial(url) → {Promise}

Parameters:
Name Type Description
url string
Source:
Returns:
Type
Promise

addEventListeners_()

Source:

addInterstitials(interstitialsnon-null)

Parameters:
Name Type Description
interstitials Array<shaka.extern.AdInterstitial>
Source:

addMetadata(hlsMetadata)

Parameters:
Name Type Description
hlsMetadata shaka.extern.HLSMetadata
Source:

addPreloadMetadata(hlsMetadata)

Handles a "com.apple.hls.preload" EXT-X-DATERANGE (RFC 8216bis Appendix F), which advises the client to preload another Date Range's resources early. We translate it into a per-interstitial resolutionTimeOffset, computed as the gap between the target's start time and the preload Date Range's start time.
Parameters:
Name Type Description
hlsMetadata shaka.extern.HLSMetadata
Source:

addUnresolvedAssetList_(descriptor)

Stores an asset list descriptor whose resolution has been deferred, and ensures the polling that will eventually resolve it is running.
Parameters:
Name Type Description
descriptor shaka.ads.InterstitialAdManager.AssetListDescriptor
Source:

applyOverlayPosition_(elementnon-null, overlaynon-null)

Positions an element within the ad container according to an overlay's viewport/topLeft/size, expressed as CSS percentages.
Parameters:
Name Type Description
element HTMLElement
overlay shaka.extern.AdPositionInfo
Source:

applyPreloadOffset_(item)

Sets resolutionTimeOffset from a matching HLS preload hint, if any.
Parameters:
Name Type Description
item {id: ?string, groupId: ?string, startTime: number, resolutionTimeOffset: (number|undefined)}
Source:

applyUpdatedPlayoutLimit_(interstitialnon-null, playoutLimit)

Applies a newly introduced X-PLAYOUT-LIMIT to an interstitial. If the interstitial is currently playing as a video ad, the playout-limit timer is re-armed so the running ad is truncated.
Parameters:
Name Type Description
interstitial shaka.extern.AdInterstitial
playoutLimit number
Source:

checkForInterstitials_()

Source:

checkPreloadOnDomElements_(interstitialnon-null)

Parameters:
Name Type Description
interstitial shaka.extern.AdInterstitial
Source:

configure(config)

Called by the AdManager to provide an updated configuration any time it changes.
Parameters:
Name Type Description
config shaka.extern.AdsConfiguration
Source:

createMediaElement_() → {HTMLMediaElement}

Source:
Returns:
Type
HTMLMediaElement

cuepointsChanged_()

Source:

determineIfUsingBaseVideo_(forceopt)

Sets usingBaseVideo_ to true if the ad can be played with the base video. Then, it either creates or destroys the adVideo_, as appropriate.
Parameters:
Name Type Attributes Default Description
force boolean <optional>
 false If true, re-create the adVideo_ if it is appropriate for playback.
Source:

getCurrentInterstitial_(needPreRollopt, numberToSkipopt, nullable) → {shaka.extern.AdInterstitial}

Parameters:
Name Type Attributes Default Description
needPreRoll boolean <optional>
 false
numberToSkip number <optional>
<nullable>
 null
Source:
Returns:
Type
shaka.extern.AdInterstitial

getInterstitials() → {Array<shaka.extern.AdInterstitial>}

Only for testing
Source:
Returns:
Type
Array<shaka.extern.AdInterstitial>

getInterstitialsInfo_(hlsMetadata) → {Promise<!Array<shaka.extern.AdInterstitial>>}

Parameters:
Name Type Description
hlsMetadata shaka.extern.HLSMetadata
Source:
Returns:
Type
Promise<!Array<shaka.extern.AdInterstitial>>

getInterstitialTimes_(hlsMetadata, idnullable) → {{startTime: number, endTime: ?number}}

Computes the start/end times of an interstitial from its HLS metadata. When the Date Range has no ID, the times are floored to a tenth of a second.
Parameters:
Name Type Attributes Description
hlsMetadata shaka.extern.HLSMetadata
id string <nullable>
Source:
Returns:
Type
{startTime: number, endTime: ?number}

getMetadataValue_(hlsMetadata, key) → {string}

Returns the string data of the HLS metadata frame with the given key, or null if there is no such frame.
Parameters:
Name Type Description
hlsMetadata shaka.extern.HLSMetadata
key string
Source:
Returns:
Type
string

getOverlaysInfo_(hlsMetadata) → {Array<shaka.extern.AdInterstitial>}

Parameters:
Name Type Description
hlsMetadata shaka.extern.HLSMetadata
Source:
Returns:
Type
Array<shaka.extern.AdInterstitial>

getPlayer() → {shaka.Player}

Source:
Returns:
Type
shaka.Player

getSortedInterstitials_() → {Array<shaka.extern.AdInterstitial>}

Returns interstitials_ sorted by descending start time, using a cache that is invalidated whenever interstitials_ changes.
Source:
Returns:
Type
Array<shaka.extern.AdInterstitial>

getTimeOffset_(interstitial) → {number}

The AD_BREAK_STARTED/ENDED time offset for an interstitial: 0 for pre-roll, -1 for post-roll, otherwise its start time.
Parameters:
Name Type Description
interstitial shaka.extern.AdInterstitial
Source:
Returns:
Type
number

getUriWithHlsParams_(uri, offsetopt) → {string}

Parameters:
Name Type Attributes Default Description
uri string
offset number <optional>
 0
Source:
Returns:
Type
string

interstitialId_(interstitial) → {string}

Parameters:
Name Type Description
interstitial shaka.extern.AdInterstitial
Source:
Returns:
Type
string

isInCooldown_() → {boolean}

Returns true if we are within the interstitialCooldown window that starts after an SGAI interstitial ad break finishes playing. While active, any snapback or next ad break should be skipped.
Source:
Returns:
Type
boolean

isPreloadAllowed_(interstitialnon-null) → {boolean}

Parameters:
Name Type Description
interstitial shaka.extern.AdInterstitial
Source:
Returns:
Type
boolean

isSmartTV_() → {boolean}

Source:
Returns:
Type
boolean

isWithinPreloadWindow_(interstitialnon-null) → {boolean}

Parameters:
Name Type Description
interstitial shaka.extern.AdInterstitial
Source:
Returns:
Type
boolean

makeAdRequest_(url, contextopt) → {shaka.net.NetworkingEngine.PendingRequest}

Parameters:
Name Type Attributes Description
url string
context shaka.extern.RequestContext <optional>
Source:
Returns:
Type
shaka.net.NetworkingEngine.PendingRequest

maybeResetAssetListsOnSeek_(currentTime)

On a seek into a live break, an already-resolved asset list must be re-requested with an updated _HLS_start_offset that reflects the new playhead position. Reset the cache of any resolved asset list whose range now contains the playhead so the poll resolves it again.
Parameters:
Name Type Description
currentTime number
Source:

maybeRetainResolvedAssetList_(descriptor)

After an asset list resolves, either retain its descriptor (so a later seek back into a live break can re-request it with an updated _HLS_start_offset) or drop it. Retaining is only useful for live streams that allow starting in the middle of an interstitial.
Parameters:
Name Type Description
descriptor shaka.ads.InterstitialAdManager.AssetListDescriptor
Source:

onSeeked_()

Source:

onTimeUpdate_()

Source:

parseCue_(hlsMetadata) → {{once: boolean, pre: boolean, post: boolean}}

Parses the CUE attribute (ONCE/PRE/POST) from HLS metadata.
Parameters:
Name Type Description
hlsMetadata shaka.extern.HLSMetadata
Source:
Returns:
Type
{once: boolean, pre: boolean, post: boolean}

processTrackingEvent_(type)

Parameters:
Name Type Description
type string
Source:

release()

Request that this object release all internal references.
Implements:
Source:

removeBaseStyles_(interstitialopt, nullable)

Parameters:
Name Type Attributes Description
interstitial shaka.extern.AdInterstitial <optional>
<nullable>
Source:

removeEventListeners_()

Source:

removeInterstitial_(interstitial)

Removes an interstitial and releases any resources associated with it (preload tasks, preload-on-DOM link elements and bookkeeping sets).
Parameters:
Name Type Description
interstitial shaka.extern.AdInterstitial
Source:

removePreloadOnDomElements_(interstitialnon-null)

Parameters:
Name Type Description
interstitial shaka.extern.AdInterstitial
Source:

removeResolvedAssetListGroup_(groupIdnullable)

Removes the interstitials previously resolved from the asset list with the given group id, so the asset list can be resolved again.
Parameters:
Name Type Attributes Description
groupId string <nullable>
Source:

resolutionAheadTime_(item) → {number}

The look-ahead time (in seconds) used to decide how early an interstitial is resolved/preloaded: the per-interstitial resolutionTimeOffset (DASH earliestResolutionTimeOffset / HLS preload Date Range) when set, otherwise the configured default.
Parameters:
Name Type Description
item {resolutionTimeOffset: (number|undefined)}
Source:
Returns:
Type
number

resolveAssetList_(descriptor) → {Promise<!Array<shaka.extern.AdInterstitial>>}

Resolves an HLS X-ASSET-LIST: performs the ad decision request and expands it into the individual interstitials it contains.
Parameters:
Name Type Description
descriptor shaka.ads.InterstitialAdManager.AssetListDescriptor
Source:
Returns:
Type
Promise<!Array<shaka.extern.AdInterstitial>>

resolveAssetListDescriptor_(descriptor)

Resolves a deferred asset list descriptor and adds the resulting interstitials. Invoked from the poll timer; not awaited.
Parameters:
Name Type Description
descriptor shaka.ads.InterstitialAdManager.AssetListDescriptor
Source:

sendEvent_(type, dictopt)

Parameters:
Name Type Attributes Description
type string
dict Map<string, Object> <optional>
Source:

setBaseStyles_(interstitial)

Parameters:
Name Type Description
interstitial shaka.extern.AdInterstitial
Source:

setupAd_(interstitial, sequenceLength, adPosition, initialTime, oncePlayedopt)

Parameters:
Name Type Attributes Default Description
interstitial shaka.extern.AdInterstitial
sequenceLength number
adPosition number
initialTime number the clock time the ad started at
oncePlayed number <optional>
 0
Source:

setupStaticAd_(interstitial, sequenceLength, adPosition, oncePlayed)

Parameters:
Name Type Description
interstitial shaka.extern.AdInterstitial
sequenceLength number
adPosition number
oncePlayed number
Source:

setupVideoAd_(interstitial, sequenceLength, adPosition, initialTime, oncePlayed)

Parameters:
Name Type Description
interstitial shaka.extern.AdInterstitial
sequenceLength number
adPosition number
initialTime number the clock time the ad started at
oncePlayed number
Source:

shouldResolveAssetListNow_(descriptor) → {boolean}

Whether the given asset list should be resolved immediately rather than deferred until playback approaches it.
Parameters:
Name Type Description
descriptor shaka.ads.InterstitialAdManager.AssetListDescriptor
Source:
Returns:
Type
boolean

shouldRetainAssetList_() → {boolean}

Whether resolved asset lists should be retained so they can be re-requested after a seek. Only meaningful for live streams that allow starting in the middle of an interstitial, where the _HLS_start_offset would differ.
Source:
Returns:
Type
boolean

stop()

Resets the Interstitial manager and removes any continuous polling.
Source:

updateInterstitials_(hlsMetadata, id)

Consolidates a subsequent EXT-X-DATERANGE that shares its ID with an already-known interstitial by augmenting it with newly added attributes, as permitted by RFC 8216bis Section 4.4.5.1. Per the spec, attributes that were already present are left unchanged; only attributes that are newly introduced are applied. This currently supports X-PLAYOUT-LIMIT, which is used to shorten (early-return from) an interstitial in live streams.
Parameters:
Name Type Description
hlsMetadata shaka.extern.HLSMetadata
id string
Source:

updatePlayerConfig_()

Source:

Type Definitions

Asset

Type:
  • {URI: string, DURATION: number, X-AD-CREATIVE-SIGNALING: ?shaka.extern.AdCreativeSignaling.CarriageEnvelope}
Properties:
Name Type Attributes Description
URI string
DURATION number
X-AD-CREATIVE-SIGNALING shaka.extern.AdCreativeSignaling.CarriageEnvelope <nullable>
Source:

AssetListDescriptor

Holds the parsed metadata of an HLS X-ASSET-LIST interstitial whose resolution has been deferred until playback approaches it.
Type:
  • {id: ?string, groupId: ?string, startTime: number, endTime: ?number, assetListUri: string, isSkippable: boolean, skipOffset: ?number, skipFor: ?number, canJump: boolean, resumeOffset: ?number, playoutLimit: ?number, once: boolean, pre: boolean, post: boolean, timelineRange: boolean, resolutionTimeOffset: (number|undefined), resolving: boolean, resolved: boolean}
Properties:
Name Type Attributes Description
id string <nullable>
groupId string <nullable>
startTime number
endTime number <nullable>
assetListUri string
isSkippable boolean
skipOffset number <nullable>
skipFor number <nullable>
canJump boolean
resumeOffset number <nullable>
playoutLimit number <nullable>
once boolean
pre boolean
post boolean
timelineRange boolean
resolutionTimeOffset number | undefined The offset in seconds before startTime at which the asset list may be resolved. Undefined or 0 means use the interstitialPreloadAheadTime default.
resolving boolean Whether a deferred resolution request is already in flight.
resolved boolean Whether the asset list has already been resolved. Retained (only for live streams that allow starting mid-interstitial) so that seeking back into the break can re-request the asset list with an updated _HLS_start_offset.
Source:

AssetsList

Type:
Properties:
Name Type Attributes Description
ASSETS Array<shaka.ads.InterstitialAdManager.Asset>
SKIP-CONTROL shaka.ads.InterstitialAdManager.SkipControl <nullable>
X-AD-CREATIVE-SIGNALING shaka.extern.AdCreativeSignaling.CarriageEnvelope <nullable>
Source:

SkipControl

Type:
  • {OFFSET: number, DURATION: number}
Properties:
Name Type Description
OFFSET number
DURATION number
Source: