Constructor
new InterstitialAdManager(adContainer, player, onEvent)
Parameters:
| Name |
Type |
Description |
adContainer |
HTMLElement
|
|
player |
shaka.Player
|
|
onEvent |
function
|
|
- Implements:
- Source:
Members
adContainer_ :HTMLElement
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:
- Source:
baseVideo_ :HTMLVideoElement
Type:
- Source:
baseVideo_ :HTMLVideoElement
Type:
- Source:
interstitialIds_ :Set<string>
Type:
- Source:
isEnded_ :boolean
Type:
- Source:
lastOnSkip_ :?function()
Type:
- Source:
lastTime_ :number
Type:
- Source:
onEvent_ :function(!shaka.util.FakeEvent)
Type:
-
function(!shaka.util.FakeEvent)
- Source:
playingAd_ :boolean
Type:
- 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:
- 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:
- Source:
sessionId_ :string
Type:
- Source:
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:
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:
- Source:
usingListeners_ :boolean
Type:
- Source:
video_ :HTMLElement
Type:
- Source:
videoCallbackId_ :number
Type:
- Source:
Methods
addAdUrlInterstitial(url) → {Promise}
Parameters:
| Name |
Type |
Description |
url |
string
|
|
- Source:
Returns:
-
Type
-
Promise
addEventListeners_()
- Source:
addInterstitials(interstitialsnon-null)
Parameters:
- Source:
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:
- 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:
- 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:
- 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:
- Source:
checkForInterstitials_()
- Source:
checkPreloadOnDomElements_(interstitialnon-null)
Parameters:
- Source:
Called by the AdManager to provide an updated configuration any time it
changes.
Parameters:
- Source:
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
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:
- Source:
Returns:
-
Type
-
{startTime: number, endTime: ?number}
Returns the string data of the HLS metadata frame with the given key, or
null if there is no such frame.
Parameters:
- Source:
Returns:
-
Type
-
string
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:
- 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:
- Source:
Returns:
-
Type
-
string
isPreloadAllowed_(interstitialnon-null) → {boolean}
Parameters:
- Source:
Returns:
-
Type
-
boolean
isSmartTV_() → {boolean}
- Source:
Returns:
-
Type
-
boolean
isWithinPreloadWindow_(interstitialnon-null) → {boolean}
Parameters:
- Source:
Returns:
-
Type
-
boolean
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:
- Source:
parseCue_(hlsMetadata) → {{once: boolean, pre: boolean, post: boolean}}
Parses the CUE attribute (ONCE/PRE/POST) from HLS metadata.
Parameters:
- 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:
- 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:
- Source:
removePreloadOnDomElements_(interstitialnon-null)
Parameters:
- 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
Resolves an HLS X-ASSET-LIST: performs the ad decision request and expands
it into the individual interstitials it contains.
Parameters:
- 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:
- Source:
sendEvent_(type, dictopt)
Parameters:
| Name |
Type |
Attributes |
Description |
type |
string
|
|
|
dict |
Map<string, Object>
|
<optional>
|
|
- Source:
setBaseStyles_(interstitial)
Parameters:
- 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:
- 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:
- 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:
- 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:
- Source:
SkipControl
Type:
-
{OFFSET: number, DURATION: number}
Properties:
| Name |
Type |
Description |
OFFSET |
number
|
|
DURATION |
number
|
|
- Source: