--- updatedAt: 2026-07-20T12:03:56.000Z agentTools: siteIndex: https://developer.bitmovin.com/llms.txt projectIndex: https://developer.bitmovin.com/playback/llms.txt --- # Server-Guided Ad Insertion HLS Interstitials and server-guided ad insertion types ## AdTrackingEvent > Interface ## 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 > Enum ## 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 *** ### VIEW\_UNDETERMINED > **VIEW\_UNDETERMINED**: `"viewUndetermined"` When the viewability of the ad cannot be determined due to technical limitations *** ### 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) *** ## CustomAttributesMappingPresets > Enum 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 > Interface Representation of an HLS interstitial ad. ## Extends * `SgaiAd` ## 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`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#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. *** ### jumpPolicy? > `optional` **jumpPolicy?**: [`JumpPolicy`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#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`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#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`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#no_seeking) Seeking restriction for the ad. Determines if seeking is allowed during ad playback. Converted from X-RESTRICT attribute by HlsInterstitialsProvider. *** ### triggerPolicy? > `optional` **triggerPolicy?**: [`TriggerPolicy`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#triggerpolicy)\[] Trigger policy for the interstitial. Defines when the interstitial should be triggered. Converted from CUE attribute by HlsInterstitialsProvider. *** ## HlsInterstitialAsset > Interface ## 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 > Interface ## Properties ### assets > **assets**: [`HlsInterstitialAsset`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#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 > Interface Tracking data on ASSET level in the ASSET-LIST ## Extends * [`InterstitialMappingData`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#interstitialmappingdata) ## Properties ### customAttributes > **customAttributes**: `object` #### Index Signature \[`key`: `string`]: `any` #### Inherited from [`InterstitialMappingData`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#interstitialmappingdata).[`customAttributes`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#customattributes) *** ### duration? > `optional` **duration?**: `number` *** ### uri > **uri**: `string` *** ## InterstitialAssetListData > Interface Tracking data on ASSET-LIST root level ## Extends * [`InterstitialMappingData`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#interstitialmappingdata) ## Properties ### customAttributes > **customAttributes**: `object` #### Index Signature \[`key`: `string`]: `any` #### Inherited from [`InterstitialMappingData`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#interstitialmappingdata).[`customAttributes`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#customattributes) *** ## InterstitialCustomAttributesMappingRegistry > Interface Registry to map custom attributes from interstitial tracking data ## Accessors ### clickThroughUrl #### Get Signature > **get** **clickThroughUrl**(): `string` Get the click through URL for the interstitial ##### Returns `string` #### Set Signature > **set** **clickThroughUrl**(`url`): `void` Set the click through URL for the interstitial ##### Parameters ###### url `string` ##### Returns `void` *** ### tracking #### Get Signature > **get** **tracking**(): [`InterstitialMappingRegistry`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#interstitialmappingregistry) Get the mapping registry for tracking events ##### Returns [`InterstitialMappingRegistry`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#interstitialmappingregistry) *** ## InterstitialData > Interface Tracking data on DATE-RANGE tag ## Extends * [`InterstitialMappingData`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#interstitialmappingdata) ## Properties ### customAttributes > **customAttributes**: `object` #### Index Signature \[`key`: `string`]: `any` #### Inherited from [`InterstitialMappingData`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#interstitialmappingdata).[`customAttributes`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#customattributes) *** ### id > **id**: `string` *** ## InterstitialMacro > Interface Macro for custom value replacement in tracking URLs ## Properties ### name > **name**: `string` *** ### value > **value**: `string` *** ## InterstitialMappingData > Interface Tracking data common to all interstitial tracking levels ## Extended by * [`InterstitialData`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#interstitialdata) * [`InterstitialAssetListData`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#interstitialassetlistdata) * [`InterstitialAssetData`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#interstitialassetdata) ## Properties ### customAttributes > **customAttributes**: `object` #### Index Signature \[`key`: `string`]: `any` *** ## InterstitialMappingRegistry > Interface Registry to register and retrieve interstitial tracking events ## Methods ### getTrackingEventsForTrigger() > **getTrackingEventsForTrigger**(`trigger`): [`AdTrackingEvent`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#adtrackingevent)\[] Get tracking events for a given trigger #### Parameters ##### trigger [`AdTrackingEventTrigger`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#adtrackingeventtrigger) The trigger for which to get tracking events #### Returns [`AdTrackingEvent`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#adtrackingevent)\[] Array of registered tracking events for the given trigger *** ### register() > **register**(`trigger`, `trackingEvents`): `void` Register tracking events for a given trigger #### Parameters ##### trigger [`AdTrackingEventTrigger`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#adtrackingeventtrigger) The trigger for which to register tracking events ##### trackingEvents [`AdTrackingEvent`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#adtrackingevent)\[] The tracking events to register #### Returns `void` *** ## InterstitialsConfig > Interface Configuration options for HLS interstitials handling ## Properties ### customAttributesMapping? > `optional` **customAttributesMapping?**: (`mappingData`, `mappingRegistry`) => `void` Custom attributes mapping callback to map tracking payload data to interstitial tracking registry #### Parameters ##### mappingData [`InterstitialData`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#interstitialdata) | [`InterstitialAssetListData`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#interstitialassetlistdata) | [`InterstitialAssetData`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#interstitialassetdata) Parsed tracking data present in the interstitial tags ##### mappingRegistry [`InterstitialCustomAttributesMappingRegistry`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#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`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#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`) => `boolean` Callback to determine if an interstitial ASSET-LIST should be loaded. The callback will be called for every interstitial ASSET-LIST before loading. #### Parameters ##### interstitial [`HlsInterstitial`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#hlsinterstitial) The interstitial to be evaluated #### Returns `boolean` Whether the interstitial should be loaded Example: ```js const playerConfig = { hls: { interstitials: { shouldLoadInterstitial: (interstitial) => { // Only load interstitials with a specific id return interstitial.id === 'pre-roll-1'; }, }, }, }; ``` *** ### shouldPlayInterstitial? > `optional` **shouldPlayInterstitial?**: (`interstitial`) => `boolean` Callback to determine if an interstitial should be played. The callback will be called for every interstitial before playback. #### Parameters ##### interstitial [`HlsInterstitial`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#hlsinterstitial) The interstitial to be evaluated #### Returns `boolean` Whether the interstitial should be played Example: ```js const playerConfig = { hls: { interstitials: { shouldPlayInterstitial: (interstitial) => { // Only play interstitials with a specific id return interstitial.id === 'pre-roll-1'; }, }, }, }; ``` *** ### shouldPlayJumpedOverInterstitials? > `optional` **shouldPlayJumpedOverInterstitials?**: (`interstitials`, `fromTime`, `toTime`) => [`HlsInterstitial`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#hlsinterstitial)\[] Callback to determine which interstitials should be played when multiple interstitials are skipped using jump #### Parameters ##### interstitials [`HlsInterstitial`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#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`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#hlsinterstitial)\[] A filtered list of interstitials that should be played Example: ```js const playerConfig = { hls: { interstitials: { shouldPlayJumpedOverInterstitials: (interstitials, fromTime, toTime) => { // Play only interstitials with duration greater than 15 seconds return interstitials.filter(interstitial => interstitial.duration > 15); }, }, }, }; ``` *** ### viewability? > `optional` **viewability?**: [`InterstitialViewabilityConfig`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#interstitialviewabilityconfig) Viewability tracking configuration for SGAI interstitial ads. *** ## InterstitialViewabilityConfig > Interface ## 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 > Enum 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. *** ## RestrictValue > Enum 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 > Enum 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. *** ## SgaiAdTrackerData > Interface 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`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#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`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#sgaiadtrackingeventdata)\[] Top level tracking events for the ad list, applicable to all ads in the list *** ## SgaiAdTrackerIdentifiers > Interface 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 > Interface 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`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#adtrackingeventtrigger) The event trigger type *** ### urls? > `optional` **urls?**: `string`\[] Array of tracking URLs for the event *** ## SgaiAdTrackingPayload > Interface 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`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#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`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#sgaiadtrackingeventdata)\[] Array of tracking events that provide tracking urls for various points in ad lifecycle *** ### type > **type**: [`LINEAR`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#linear) The type of the ad *** ### verification? > `optional` **verification?**: [`SgaiAdTrackingVerificationData`](https://developer.bitmovin.com/playback/reference/web-sdk-sgai#sgaiadtrackingverificationdata)\[] Array of verification data to provide ad verification provider resources *** ## SgaiAdTrackingVerificationData > Interface 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 Enum representing different types of SGAI ads ## Enumeration Members ### LINEAR > **LINEAR**: `"linear"` A basic duration based media asset *** ## TriggerPolicy > Enum 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.