Constructor
new InterstitialAdManager(adContainer, player, onEvent, configurePlayeropt, createTrackeropt)
Parameters:
| Name |
Type |
Attributes |
Description |
adContainer |
HTMLElement
|
|
|
player |
shaka.Player
|
|
|
onEvent |
function
|
|
|
configurePlayer |
function
|
<optional>
|
Configures the player of an interstitial. |
createTracker |
shaka.ads.InterstitialAdSession.TrackerFactory
|
<optional>
|
Creates the format specific tracker of an interstitial. |
- Implements:
- Source:
Members
PLAYOUT_LIMIT_TOLERANCE_ :number
Margin, in seconds, within which the playout limit of an ad is considered
reached when its media ends. Playback is measured from timeupdate events,
which stop slightly before the end of the media.
Type:
- Source:
adContainer_ :HTMLElement
Type:
- Source:
baseVideo_ :HTMLVideoElement
Type:
- Source:
baseVideo_ :HTMLVideoElement
Type:
- Source:
Type:
-
function(!shaka.Player, ?shaka.extern.AdInterstitial)
- Source:
Interstitial resources 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:
embeddedClickTarget_ :HTMLElement
Receives clicks on the current embedded slot, which has no element of
its own in the ad container.
Type:
- Source:
embeddedGroup_ :string
Type:
- Source:
generation_ :number
Type:
- Source:
hasEmbeddedInterstitials_ :boolean
Type:
- Source:
interstitialIds_ :Set<string>
Type:
- Source:
isEnded_ :boolean
Type:
- Source:
lastAdCompleteTime_ :number
Wall-clock time (ms) when the last SGAI interstitial ad break finished
playing. Used to enforce the interstitialCooldown config.
Type:
- Source:
lastOnPlayoutLimit_ :?function()
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:
Playout of the interstitial being played. Only media actually played
counts, so loading or rebuffering its assets does not consume its
playout limit.
Type:
- Source:
preloadOffsets_ :Map<string, number>
Preload hints (e.g. HLS "com.apple.hls.preload" Date Ranges, RFC 8216bis
Appendix F): maps the target ID to the time at which its resources may
start being resolved.
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:
usingBaseVideo_ :boolean
Type:
- Source:
usingListeners_ :boolean
Type:
- Source:
video_ :HTMLElement
Type:
- Source:
videoCallbackId_ :number
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
addDeferredInterstitial(descriptornon-null) → {Promise}
Registers a resource whose resolution is controlled by the common
scheduler. The resolver owns the resource's format and request details.
Parameters:
- Source:
Returns:
-
Type
-
Promise
addEventListeners_()
- Source:
addInterstitials(interstitialsnon-null)
Parameters:
- Source:
addPreloadHint(targetId, startTime)
Advises that the resources of the interstitial (or deferred resource) with
the given ID may be resolved from the given time on. It is translated into
a resolutionTimeOffset, computed as the gap between the target's start
time and the hint's start time.
Parameters:
| Name |
Type |
Description |
targetId |
string
|
|
startTime |
number
|
|
- 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 preload hint, if any.
Parameters:
| Name |
Type |
Description |
item |
{id: ?string, groupId: (?string|undefined), startTime: number, resolutionTimeOffset: (number|undefined)}
|
|
- Source:
applyUpdatedPlayoutLimit_(interstitialnon-null, playoutLimit)
Applies a newly introduced 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
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
interstitialId_(interstitial) → {string}
Parameters:
- 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:
- Source:
Returns:
-
Type
-
boolean
isSmartTV_() → {boolean}
- Source:
Returns:
-
Type
-
boolean
isWithinPreloadWindow_(interstitialnon-null) → {boolean}
Parameters:
- Source:
Returns:
-
Type
-
boolean
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:
removeResolvedGroup_(groupIdnullable)
Removes the interstitials previously resolved from the resource with the
given group id, so the resource can be resolved again.
Parameters:
| Name |
Type |
Attributes |
Description |
groupId |
string
|
<nullable>
|
|
- Source:
resetResourcesOnSeek_(currentTime)
On a seek into a live break, an already-resolved resource must be
re-requested with an updated playback offset that reflects the new
playhead position. Reset the cache of any resolved resource whose range
now contains the playhead so the poll resolves it again.
Parameters:
| Name |
Type |
Description |
currentTime |
number
|
|
- 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
resolveDeferredInterstitial_(descriptor)
Resolves a deferred resource descriptor and adds the resulting
interstitials. Invoked from the poll timer; not awaited.
Parameters:
- Source:
retainResolvedResource_(descriptor)
After an resource resolves, either retain its descriptor (so a later seek
back into a live break can re-request it with an updated playback offset)
or drop it. Retaining is only useful for live streams that allow starting
in the middle of an interstitial.
Parameters:
- Source:
sendBeacon_(uri)
Parameters:
| Name |
Type |
Description |
uri |
string
|
|
- Source:
sendEvent_(type, dictopt)
Parameters:
| Name |
Type |
Attributes |
Description |
type |
string
|
|
|
dict |
Map<string, ?>
|
<optional>
|
|
- Source:
sendEventForAd_(interstitialnon-null, type, dictopt)
Parameters:
- 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:
shouldResolveResourceNow_(descriptor) → {boolean}
Whether the given resource should be resolved immediately rather than
deferred until playback approaches it.
Parameters:
- Source:
Returns:
-
Type
-
boolean
shouldRetainResource_() → {boolean}
Whether resolved resources 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 playback offset would differ.
- Source:
Returns:
-
Type
-
boolean
stop()
Resets the Interstitial manager and removes any continuous polling.
- Source:
stopEmbeddedInterstitial_(typenullable)
Ends the current embedded slot.
Parameters:
| Name |
Type |
Attributes |
Description |
type |
string
|
<nullable>
|
The event that explains the end, if any. |
- Source:
updateEmbeddedInterstitial_(seekedopt)
Updates embedded slots independently of the insertion scheduler. Loading
or seeking into a slot activates its half-open interval immediately;
insertion cooldown and snapback policies do not apply to existing media.
Parameters:
| Name |
Type |
Attributes |
Default |
Description |
seeked |
boolean
|
<optional>
|
false
|
|
- Source:
updateInterstitial(id, playoutLimit)
Applies a newly supplied playout limit to a scheduled ad or resource.
Existing limits remain unchanged.
Parameters:
| Name |
Type |
Description |
id |
string
|
|
playoutLimit |
number
|
|
- Source:
updatePlayerConfig_(interstitialopt, nullable)
Parameters:
- Source:
Type Definitions
Playout
Type:
-
{id: ?string, limit: number, played: number}
Properties:
| Name |
Type |
Attributes |
Description |
id |
string
|
<nullable>
|
The interstitial, or group of interstitials, the playout belongs to. |
limit |
number
|
|
The playout limit, in seconds, or Infinity. |
played |
number
|
|
The media played so far, in seconds. |
- Source: