Server-Guided Ad Insertion

AdTrackingEvent

Properties

offset

• Optional offset: number

The offset(absolute time in seconds) when the progress event should be fired

urls

• urls: string[]

The tracking URL to fire when this event is triggered

AdTrackingEventTrigger

Enumeration Members

CLICKED

• CLICKED = "clickTracking"

When the ad has been clicked

COMPLETE

• COMPLETE = "complete"

When the ad has been completed

ERROR

• ERROR = "error"

When an error has occurred during ad playback

FIRST_QUARTILE

• FIRST_QUARTILE = "firstQuartile"

When 25% of the ad has been played

IMPRESSION

• IMPRESSION = "impression"

When the impression of ad creative occurs

LOADED

• LOADED = "loaded"

When the ad has been loaded

MIDPOINT

• MIDPOINT = "midpoint"

When 50% of the ad has been played

MUTE

• MUTE = "mute"

When a user action has caused the ad to be muted

NOT_VIEWABLE

• NOT_VIEWABLE = "notViewable"

When the ad is not viewable according to the viewability definition

PAUSE

• PAUSE = "pause"

When a user action has caused the ad to be paused

PROGRESS

• PROGRESS = "progress"

When the ad has been playing for a duration equal to the signaled offset

RESUME

• RESUME = "resume"

When a user action has caused the ad to be resumed from paused state

SKIP

• SKIP = "skip"

When the ad has been skipped

START

• START = "start"

When the ad is started

THIRD_QUARTILE

• THIRD_QUARTILE = "thirdQuartile"

When 75% of the ad has been played

UNMUTE

• UNMUTE = "unmute"

When a user action has caused the ad to be unmuted

VIEWABLE

• VIEWABLE = "viewable"

When the ad is viewable according to the viewability definition
(e.g. 50% of the ad is visible for at least 2 seconds)

VIEW_UNDETERMINED

• VIEW_UNDETERMINED = "viewUndetermined"

When the viewability of the ad cannot be determined due to technical limitations

CustomAttributesMappingPresets

Presets for standard custom attributes mapping

Enumeration Members

AD_CREATIVE_SIGNALING

• AD_CREATIVE_SIGNALING = "AD-CREATIVE-SIGNALING"

Standard mapping based on the "X-AD-CREATIVE-SIGNALING" SVTA specification.

NONE

• NONE = "NONE"

No standard mapping applied.

HlsInterstitial

Representation of an HLS interstitial ad.

Hierarchy

SgaiAd

↳ HlsInterstitial

Properties

adCreativeSignaling

• Optional adCreativeSignaling: any

Ad creative signaling data, if present.
The data could be present either on ASSET-LIST level or DATE-RANGE level based on SVTA spec.

assetList

• Optional assetList: HlsInterstitialAssetList

Asset list data, if present.
The parsed JSON object returned by the URL in assetListUri.

assetListUri

• Optional assetListUri: string

The URL to a JSON object containing a list of interstitials “ASSETS”. Parsed from X-ASSET-LIST.
If defined, this takes precedence over assetUri.

assetUri

• Optional assetUri: string

An absolute URL for a single interstitial asset. Parsed from X-ASSET-URI.
If assetListUri is defined, this property should be ignored.

customAttributes

• Optional customAttributes: Object

Any attributes that is not known in the HLS interstitial spec.
The tracking information could be present here, X-AD-CREATIVE-SIGNALING in case of SVTA.

Index signature

▪ [key: string]: any

duration

• Optional duration: number

The actual duration of the interstitial in seconds, if known, otherwise undefined.
May differ from end - start, as the end time is always populated with a default of +1.

end

• end: number

The end time for the ad in seconds.

Inherited from

SgaiAd.end

id

• id: string

The unique identifier for the ad.

Inherited from

SgaiAd.id

jumpPolicy

• Optional jumpPolicy: JumpPolicy

Jump policy for the ad. Determines if at least one ad must play when jumping over multiple ads.
Converted from X-RESTRICT attribute by HlsInterstitialsProvider.

plannedDuration

• Optional plannedDuration: number

The expected duration in seconds of the interstitial if duration is not yet known.
Usually populated if the interstitial is dynamically updated or features an asset list.

playoutLimit

• Optional playoutLimit: number

Value from X-PLAYOUT-LIMIT header.
Defines how long the interstitial is expected to play for, in seconds.
Should be intended as a way to exit an interstitial early.

restrict

• Optional restrict: RestrictValue[]

Values from X-RESTRICT header (enumerated-string-list).
Defines restrictions on seeking/playback behavior during the interstitial.
Can contain multiple restriction values (e.g., [SKIP, JUMP]).

resumeOffset

• Optional resumeOffset: number

Value from X-RESUME-OFFSET header.
Defines how much content should be replaced by the interstitial ad.
If undefined, the duration of the ad(s) should be used.

seekingRestriction

• Optional seekingRestriction: NO_SEEKING

Seeking restriction for the ad. Determines if seeking is allowed during ad playback.
Converted from X-RESTRICT attribute by HlsInterstitialsProvider.

start

• start: number

The scheduled start time for the ad in seconds.

Inherited from

SgaiAd.start

triggerPolicy

• Optional triggerPolicy: TriggerPolicy[]

Trigger policy for the interstitial. Defines when the interstitial should be triggered.
Converted from CUE attribute by HlsInterstitialsProvider.

HlsInterstitialAsset

Properties

customAttributes

• Optional customAttributes: Object

Any attributes that is not known in the HLS interstitial asset spec.
The tracking information could be present here, X-AD-CREATIVE-SIGNALING in case of SVTA.

Index signature

▪ [key: string]: any

duration

• duration: number

The duration of the interstitial asset in seconds.

uri

• uri: string

The URI of the interstitial asset.

HlsInterstitialAssetList

Properties

assets

• assets: HlsInterstitialAsset[]

Array of interstitial assets in the asset list.

customAttributes

• Optional customAttributes: Object

Any attributes that is not known in the HLS interstitial asset list spec.
The tracking information could be present here, X-AD-CREATIVE-SIGNALING in case of SVTA.

Index signature

▪ [key: string]: any

InterstitialAssetData

Tracking data on ASSET level in the ASSET-LIST

Hierarchy

InterstitialMappingData

↳ InterstitialAssetData

Properties

customAttributes

• customAttributes: Object

Index signature

▪ [key: string]: any

Inherited from

InterstitialMappingData.customAttributes

duration

• Optional duration: number

uri

• uri: string

InterstitialAssetListData

Tracking data on ASSET-LIST root level

Hierarchy

InterstitialMappingData

↳ InterstitialAssetListData

Properties

customAttributes

• customAttributes: Object

Index signature

▪ [key: string]: any

Inherited from

InterstitialMappingData.customAttributes

InterstitialCustomAttributesMappingRegistry

Registry to map custom attributes from interstitial tracking data

Accessors

clickThroughUrl

• get clickThroughUrl(): string

Get the click through URL for the interstitial

Returns

string

• set clickThroughUrl(url): void

Set the click through URL for the interstitial

Parameters

Name	Type
`url`	`string`

Returns

void

tracking

• get tracking(): InterstitialMappingRegistry

Get the mapping registry for tracking events

Returns

InterstitialMappingRegistry

InterstitialData

Tracking data on DATE-RANGE tag

Hierarchy

InterstitialMappingData

↳ InterstitialData

Properties

customAttributes

• customAttributes: Object

Index signature

▪ [key: string]: any

Inherited from

InterstitialMappingData.customAttributes

id

• id: string

InterstitialMacro

Macro for custom value replacement in tracking URLs

Properties

name

• name: string

value

• value: string

InterstitialMappingData

Tracking data common to all interstitial tracking levels

Hierarchy

InterstitialMappingData

↳ InterstitialData

↳ InterstitialAssetListData

↳ InterstitialAssetData

Properties

customAttributes

• customAttributes: Object

Index signature

▪ [key: string]: any

InterstitialMappingRegistry

Registry to register and retrieve interstitial tracking events

Methods

getTrackingEventsForTrigger

▸ getTrackingEventsForTrigger(trigger): AdTrackingEvent[]

Get tracking events for a given trigger

Parameters

Name	Type	Description
`trigger`	`AdTrackingEventTrigger`	The trigger for which to get tracking events

Returns

AdTrackingEvent[]

Array of registered tracking events for the given trigger

register

▸ register(trigger, trackingEvents): void

Parameters

Name	Type	Description
`trigger`	`AdTrackingEventTrigger`	The trigger for which to register tracking events
`trackingEvents`	`AdTrackingEvent`[]	The tracking events to register

Returns

void

InterstitialsConfig

Configuration options for HLS interstitials handling

Properties

customAttributesMapping

• Optional customAttributesMapping: (mappingData: InterstitialData | InterstitialAssetListData | InterstitialAssetData, mappingRegistry: InterstitialCustomAttributesMappingRegistry) => void

Custom attributes mapping callback to map tracking payload data to interstitial tracking registry

Type declaration

▸ (mappingData, mappingRegistry): void

Parameters

Name	Type	Description
`mappingData`	`InterstitialData` \| `InterstitialAssetListData` \| `InterstitialAssetData`	Parsed tracking data present in the interstitial tags
`mappingRegistry`	`InterstitialCustomAttributesMappingRegistry`	Registry to register tracking events Example: js const playerConfig = { hls: { interstitials: { customAttributesMapping(mappingData, mappingRegistry) { const adCreativeSignaling = mappingData.customAttributes['X-AD-CREATIVE-SIGNALING']; const payload = adCreativeSignaling.payload; if (!payload) { return; } const firstPayload = payload[0]; const clickThroughUrl = firstPayload.clickThrough; if (clickThroughUrl) { mappingRegistry.clickThroughUrl = clickThroughUrl; } const trackingData = firstPayload.tracking; if (trackingData) { for (const trackingEvent of trackingData) { const eventType = trackingEvent.type; const urls = trackingEvent.urls; const offset = trackingEvent.offset; if (!eventType \|\| !urls) { continue; } switch (eventType) { case InterstitialTrackingEventTrigger.IMPRESSION: mappingRegistry.tracking.register( InterstitialTrackingEventTrigger.IMPRESSION, { urls, offset }, ); break; } } } }, }, }, };

Returns

void

customAttributesMappingPreset

• Optional customAttributesMappingPreset: CustomAttributesMappingPresets

Preset for standard custom attributes mapping
When set, the player will automatically map standard custom attributes based on the selected preset.

Default is CustomAttributesMappingPresets.NONE

When InterstitialsConfig.customAttributesMapping is set, this property is ignored.
When set to CustomAttributesMappingPresets.AD_CREATIVE_SIGNALING, SVTA "X-AD-CREATIVE-SIGNALING" mapping is applied.

shouldLoadInterstitial

• Optional shouldLoadInterstitial: (interstitial: HlsInterstitial) => boolean

Callback to determine if an interstitial ASSET-LIST should be loaded.
The callback will be called for every interstitial ASSET-LIST before loading.

Type declaration

▸ (interstitial): boolean

Parameters

Name	Type	Description
`interstitial`	`HlsInterstitial`	The interstitial to be evaluated

Returns

boolean

shouldPlayInterstitial

• Optional shouldPlayInterstitial: (interstitial: HlsInterstitial) => boolean

Callback to determine if an interstitial should be played.
The callback will be called for every interstitial before playback.

Type declaration

▸ (interstitial): boolean

Parameters

Name	Type	Description
`interstitial`	`HlsInterstitial`	The interstitial to be evaluated

Returns

boolean

shouldPlayJumpedOverInterstitials

• Optional shouldPlayJumpedOverInterstitials: (interstitials: HlsInterstitial[], fromTime: number, toTime: number) => HlsInterstitial[]

Callback to determine which interstitials should be played when multiple interstitials are skipped using jump

Type declaration

▸ (interstitials, fromTime, toTime): HlsInterstitial[]

Parameters

Name	Type	Description
`interstitials`	`HlsInterstitial`[]	A list of interstitials to be evaluated
`fromTime`	`number`	The start time of the jump operation in seconds
`toTime`	`number`	The end time of the jump operation in seconds

Returns

HlsInterstitial[]

viewability

• Optional viewability: InterstitialViewabilityConfig

Viewability tracking configuration for SGAI interstitial ads.

InterstitialViewabilityConfig

Properties

decisionTimeout

• Optional decisionTimeout: number

Maximum time window in seconds within which the viewability decision must be made.

If no viewable decision is made within this window, the tracker emits notViewable.
When omitted, defaults to the ad's duration.

Default: ad duration

viewableDuration

• Optional viewableDuration: number

The amount of consecutive seconds the interstitial should stay visible in order to emit the viewable tracking event.

Default: 2

JumpPolicy

Jump over ads policy for HLS interstitial playback.
Derived from X-RESTRICT header in HLS manifests.

Enumeration Members

ALLOW

• ALLOW = "ALLOW"

ALLOW: Ad break can be jumped over without restriction.
Corresponds to no X-RESTRICT or X-RESTRICT without "JUMP".

RESTRICT

• RESTRICT = "RESTRICT"

RESTRICT: Ad break cannot be jumped over, at least one ad must play.
Corresponds to X-RESTRICT="JUMP" header.

PlayerSgaiAPI

Methods

getActiveAd

▸ getActiveAd(): LinearAd

Returns the currently active SGAI ad, if any.

Returns

LinearAd

list

▸ list(): HlsInterstitial[] | SgaiAd[]

Returns a list of all SGAI ads that are scheduled for playback. Does not include current active ad.

Returns

HlsInterstitial[] | SgaiAd[]

skip

▸ skip(): Promise<void>

Skips the currently playing ad.

Returns

Promise<void>

RestrictValue

Enum for X-RESTRICT header values that control playback behavior during ads.
SGAI (Server-Guided Ad Insertion) specification support.

Enumeration Members

JUMP

• JUMP = "JUMP"

JUMP: When jumping over multiple ads, at least one ad must play.
Used with JumpPolicy.RESTRICT.

SKIP

• SKIP = "SKIP"

SKIP: Seeking or playing at higher rate while playing ads should not be allowed.
Corresponds to SeekingRestriction.NO_SEEKING.

SeekingRestriction

Seeking restriction policy for HLS interstitial playback.
Derived from X-RESTRICT header in HLS manifests.
When undefined, no seeking restrictions are applied.

Enumeration Members

NO_SEEKING

• NO_SEEKING = "NO_SEEKING"

NO_SEEKING: Seeking or playing at higher rate while playing ads should not be allowed.
Corresponds to X-RESTRICT=SKIP header.

SgaiAd

Ƭ SgaiAd: Object

Type declaration

Name	Type	Description
`end`	`number`	The end time for the ad in seconds.
`id`	`string`	The unique identifier for the ad.
`start`	`number`	The scheduled start time for the ad in seconds.

SgaiAdBreak

Hierarchy

AdBreak

↳ SgaiAdBreak

Properties

adCreativeSignaling

• Optional adCreativeSignaling: SgaiAdTrackerData

Ad creative signaling data for the ad break.
Top level ad creative signaling present in ASSET-LIST applicable to the entire ad break.
For ASSET-URI, this value is present on DATE-RANGE level.

Parsed based on SVTA spec

• Optional ads: SgaiLinearAd[]

The list of ads to be played during this ad break.

Overwrite the ads type in AdBreak

Overrides

AdBreak.ads

customAdTrackingInfo

• Optional customAdTrackingInfo: any

Custom ad tracking information for the ad break.

id

• id: string

The id of the corresponding AdBreakConfig.
If the AdBreak was generated out of a VMAP tag, then the ID present in the
VMAP tag will be taken. If none is present in the VMAP tag, it will be generated.

Inherited from

AdBreak.id

replaceContentDuration

• Optional replaceContentDuration: number

Specifies how many seconds the ad break(s) should replace of the main video content.

Inherited from

AdBreak.replaceContentDuration

restrictions

• Optional restrictions: PlaybackRestrictions

Playback restrictions to apply during ad playback (e.g., seeking, playback rate changes).

scheduleTime

• scheduleTime: number

The time in seconds in the media timeline the AdBreak is scheduled for.

Inherited from

AdBreak.scheduleTime

SgaiAdBreakPlaybackContext

Ƭ SgaiAdBreakPlaybackContext: Object

Type declaration

Name	Type	Description
`getPlayoutLimit`	() => `number` \| `undefined`	-
`isLastAdBreak`	`boolean`	Indicates whether the passed-in ad break is the last one in the current playback sequence. This is used to decide whether main content should be restored afterwards.

SgaiAdTrackerData

Top level tracking data parsed on ASSET-LIST level

Properties

duration

• duration: number

Total duration of all ads in the asset list in seconds

payload

• Optional payload: SgaiAdTrackingPayload[]

Array of ad tracking payloads for each ad in the asset list

start

• Optional start: number

The start time of the ad list within the primary content timeline

tracking

• Optional tracking: SgaiAdTrackingEventData[]

Top level tracking events for the ad list, applicable to all ads in the list

SgaiAdTrackerIdentifiers

Describes a single ad identifier used to uniquely identify an ad

Properties

scheme

• scheme: string

A scheme URI that identifies the definition authority for the related identification value

value

• value: string

An identifier value that can be interpreted using the semantics of the named scheme.

SgaiAdTrackingEventData

Describes a single tracking event for an ad used within ad lifecycle

Properties

duration

• Optional duration: number

Duration in seconds

offset

• Optional offset: number

Offset in seconds relative to reference object (DATE-RANGE/ASSET-LIST) when the event should be triggered

start

• Optional start: number

Start time in seconds

type

• type: AdTrackingEventTrigger

The event trigger type

urls

• Optional urls: string[]

Array of tracking URLs for the event

SgaiAdTrackingPayload

Tracking data parsed on DATE-RANGE or inner ads in ASSET-LIST level

Properties

clickThrough

• Optional clickThrough: string

Optional click through url for the ad

duration

• duration: number

The duration of the ad in seconds

identifiers

• identifiers: SgaiAdTrackerIdentifiers[]

Array of ad identifiers to uniquely identify the ad

start

• start: number

The start time of the ad within the primary content timeline or related to start of asset-list

tracking

• Optional tracking: SgaiAdTrackingEventData[]

Array of tracking events that provide tracking urls for various points in ad lifecycle

type

• type: LINEAR

The type of the ad

verification

• Optional verification: SgaiAdTrackingVerificationData[]

Array of verification data to provide ad verification provider resources

SgaiAdTrackingVerificationData

Describes a resource and parameters that can be utilized to initialize and operate
an ad verification provider Software Development Kit (SDK)

Properties

parameters

• Optional parameters: string

The parameters that can be used to initialize the vendor verification system

resource

• Optional resource: string

URI representing a resource that is part of the vendor verification system

vendor

• vendor: string

Identifies the vendor context that the resource and parameters can be interpreted in

SgaiAdType

Enum representing different types of SGAI ads

Enumeration Members

LINEAR

• LINEAR = "linear"

A basic duration based media asset

SgaiLinearAd

Defines a linear ad which requires the playback of the content to stop

Hierarchy

LinearAd

↳ SgaiLinearAd

Properties

adCreativeSignaling

• Optional adCreativeSignaling: SgaiAdTrackerData

The ad creative signaling data associated with this ad.
This data is used for ad tracking and reporting purposes.

Parsed based on SVTA spec

clickThroughUrl

• Optional clickThroughUrl: string

The url the user should be redirected to when clicking the ad.

Inherited from

LinearAd.clickThroughUrl

clickThroughUrlOpened

• Optional clickThroughUrlOpened: () => void

Callback function to track the opening of the clickThroughUrl.

Type declaration

▸ (): void

Returns

void

Inherited from

LinearAd.clickThroughUrlOpened

companionAds

• Optional companionAds: CompanionAd[]

The CompanionAds that should be served with the ad.

Inherited from

LinearAd.companionAds

customAdTrackingInfo

• Optional customAdTrackingInfo: any

Custom ad tracking information.

data

• Optional data: AdData

Holds various additional ad data.

Inherited from

LinearAd.data

duration

• duration: number

The duration of the ad.

Inherited from

LinearAd.duration

extensions

• Optional extensions: VastAdExtension[]

The parsed custom Extension tags

Since: 8.39.0

Inherited from

LinearAd.extensions

height

• height: number

The height of the ad.

Inherited from

LinearAd.height

id

• Optional id: string

Identifier for the ad. This might be autogenerated.

Inherited from

LinearAd.id

isLinear

• isLinear: boolean

Determines whether an ad is linear, i.e. playback of main content needs to be paused for the ad.

Inherited from

LinearAd.isLinear

mediaFileUrl

• Optional mediaFileUrl: string

The corresponding media file for the ad.

Inherited from

LinearAd.mediaFileUrl

skippable

• Optional skippable: boolean

Specifies whether the ad is skippable or not.

Deprecated: - This will be removed with player version 9. This can be inferred from skippableAfter

Inherited from

LinearAd.skippable

skippableAfter

• Optional skippableAfter: number

Time in seconds, after which the ad is skippable. The ad is not skippable if this property is not set.

Inherited from

LinearAd.skippableAfter

uiConfig

• Optional uiConfig: LinearAdUiConfig

Holds relevant information for displaying the ad.

Inherited from

LinearAd.uiConfig

verifications

• Optional verifications: any[]

The parsed Verification tags of the corresponding AdVerifications tag. Every tag is handled as an array and the
property names are the exact same as the tag/attribute names found in the manifest (case-sensitive). The text
content of a tag is saved to a content property.

Inherited from

LinearAd.verifications

width

• width: number

The width of the ad.

Inherited from

LinearAd.width

SgaiProvider

Hierarchy

Disposable

↳ SgaiProvider

Methods

clearDroppedOutAds

▸ clearDroppedOutAds(): void

Returns

void

getDueAds

▸ getDueAds(time): SgaiAd[]

Parameters

Name	Type
`time`	`number`

Returns

SgaiAd[]

getPostRollAds

▸ getPostRollAds(): SgaiAd[]

Returns

SgaiAd[]

getPreRollAds

▸ getPreRollAds(): SgaiAd[]

Returns

SgaiAd[]

getReplaceContentDuration

▸ getReplaceContentDuration(ad, nestedAds): number

Parameters

Name	Type
`ad`	`SgaiAd`
`nestedAds`	`SgaiLinearAd`[]

Returns

number

getTotalPlannedDuration

▸ getTotalPlannedDuration(ad, nestedAds): number

Parameters

Name	Type
`ad`	`SgaiAd`
`nestedAds`	`SgaiLinearAd`[]

Returns

number

getTotalPlayoutLimit

▸ getTotalPlayoutLimit(ad): number

Parameters

Name	Type
`ad`	`SgaiAd`

Returns

number

handleSkippedAds

▸ handleSkippedAds(fromTime, toTime): SgaiAd[]

Parameters

Name	Type
`fromTime`	`number`
`toTime`	`number`

Returns

SgaiAd[]

listUnplayedAds

▸ listUnplayedAds(): SgaiAd[]

Returns

SgaiAd[]

markAdAsPlayed

▸ markAdAsPlayed(ad): void

Parameters

Name	Type
`ad`	`SgaiAd`

Returns

void

preloadUpcomingAds

▸ preloadUpcomingAds(time): void

Parameters

Name	Type
`time`	`number`

Returns

void

reinsertAds

▸ reinsertAds(seekTarget): void

Parameters

Name	Type
`seekTarget`	`number`

Returns

void

resolveAdCreativeSignaling

▸ resolveAdCreativeSignaling(ad): SgaiAdTrackerData

Parameters

Name	Type
`ad`	`SgaiAd`

Returns

SgaiAdTrackerData

resolveNestedAds

▸ resolveNestedAds(ad): Promise<SgaiLinearAd[]>

Parameters

Name	Type
`ad`	`SgaiAd`

Returns

Promise<SgaiLinearAd[]>

resolveRestrictions

▸ resolveRestrictions(ad): PlaybackRestrictions

Parameters

Name	Type
`ad`	`SgaiAd`

Returns

PlaybackRestrictions

TriggerPolicy

Trigger policy for HLS interstitial playback.
Derived from CUE attribute in HLS manifests.

Enumeration Members

ONCE

• ONCE = "ONCE"

ONCE: Trigger the interstitial only once during the main content.

POST

• POST = "POST"

POST: Trigger the interstitial after the main content ends.

PRE

• PRE = "PRE"

PRE: Trigger the interstitial before the main content starts.