API Reference
Bitmovin PlatformPlaybackEncodingBitmovin Dashboard

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

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

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.

triggerPolicy?

optional triggerPolicy?: 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[]

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

Properties

customAttributes

customAttributes: object

Index Signature

[key: string]: any

Inherited from

InterstitialMappingData.customAttributes

duration?

optional duration?: number

uri

uri: string

InterstitialAssetListData

Interface

Tracking data on ASSET-LIST root level

Extends

Properties

customAttributes

customAttributes: object

Index Signature

[key: string]: any

Inherited from

InterstitialMappingData.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

Get the mapping registry for tracking events

Returns

InterstitialMappingRegistry

InterstitialData

Interface

Tracking data on DATE-RANGE tag

Extends

Properties

customAttributes

customAttributes: object

Index Signature

[key: string]: any

Inherited from

InterstitialMappingData.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

Properties

customAttributes

customAttributes: object

Index Signature

[key: string]: any

InterstitialMappingRegistry

Interface

Registry to register and retrieve interstitial tracking events

Methods

getTrackingEventsForTrigger()

getTrackingEventsForTrigger(trigger): AdTrackingEvent[]

Get tracking events for a given trigger

Parameters

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

Register tracking events for a given trigger

Parameters

trigger

AdTrackingEventTrigger

The trigger for which to register tracking events

trackingEvents

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 | InterstitialAssetListData | InterstitialAssetData

Parsed tracking data present in the interstitial tags

mappingRegistry

InterstitialCustomAttributesMappingRegistry

Registry to register tracking events

Example:

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) => 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

The interstitial to be evaluated

Returns

boolean

Whether the interstitial should be loaded

Example:

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

The interstitial to be evaluated

Returns

boolean

Whether the interstitial should be played

Example:

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[]

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

Parameters

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[]

A filtered list of interstitials that should be played

Example:

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

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[]

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

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

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[]

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

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.

Updated 11 days ago

Did this page help you?

Updated 11 days ago

Did this page help you?