API Reference
Bitmovin PlatformPlaybackEncodingBitmovin Dashboard

Advertising - IMA Module

Google IMA SDK integration configuration

google.ima.AdsManager

Type

AdsManager = any

See

https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/reference/js/google.ima.AdsManager

google.ima.AdsRequest

Type

AdsRequest = any

See

https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/reference/js/google.ima.AdsRequest

google.ima.ImaSdkSettings

Type

ImaSdkSettings = any

See

https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/reference/js/google.ima.ImaSdkSettings

ImaAdBreak

Interface

Ad break returned by the IMA advertising module.

Extends

Properties

ads?

optional ads?: Ad[]

The ads scheduled for this AdBreak.

Inherited from

AdBreak.ads

discardAfterPlayback?

optional discardAfterPlayback?: boolean

Specifies whether ad breaks are discarded after they are played back, played over or tried to be played back but
failed due to some condition.
When set to false, ad breaks are played again when seeking back to a previous ad break position and never
discarded in any of the above cases.

The flag will be ignored when ImaAdTagConfig.passthroughMode
is set to ImaPassthroughMode.VastAndVmap

Default is true.

Inherited from

ImaAdBreakConfig.discardAfterPlayback

fallbackTags?

optional fallbackTags?: AdTag[]

Defines a list of fallback ad tags which will be tried one after the other if the original ad tag does not
provide a valid response. The fallback ad tags need to have the same AdTagType as the main tag.

Inherited from

ImaAdBreakConfig.fallbackTags

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

linearAdUiConfig?

optional linearAdUiConfig?: LinearAdUiConfig

Holds relevant information for the advertising UI.

Inherited from

ImaAdBreakConfig.linearAdUiConfig

passthroughMode?

optional passthroughMode?: ImaPassthroughMode

Indicates which ad tags should be downloaded by the IMA SDK instead of by the Player. This can be helpful if
ad servers expect the IMA SDK to add some specific parameters to the request.

Inherited from

ImaAdBreakConfig.passthroughMode

persistent?

optional persistent?: boolean

If set, the ad tag will be processed and rescheduled automatically when a new source is loaded.

Inherited from

ImaAdBreakConfig.persistent

position

position: string

Defines when the ad break shall be started. Default is 'pre'.

Allowed values are:

  • 'pre': pre-roll ad
  • 'post': post-roll ad
  • fractional seconds: '10', '12.5' (mid-roll ad)
  • percentage of the entire video duration: '25%', '50%' (mid-roll ad)
  • timecode [hh:mm:ss.mmm]: '00:10:30.000', '01:00:00.000' (mid-roll ad)

Inherited from

ImaAdBreakConfig.position

preloadOffset?

optional preloadOffset?: number

Specifies how many seconds before the ad break would start playing should the ad tag (and if possible the media
files of the resulting ad response) start pre-loading.
Default is 0.

Inherited from

ImaAdBreakConfig.preloadOffset

replaceContentDuration?

optional replaceContentDuration?: number

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

Inherited from

AdBreak.replaceContentDuration

scheduleTime

scheduleTime: number

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

Inherited from

AdBreak.scheduleTime

tag

tag: AdTag

Defines the url and type of the ad manifest. If the tag is a VAST or VPAID manifest, then more specific
scheduling options can be defined in the AdBreakConfig.

Inherited from

ImaAdBreakConfig.tag

trackingEvents?

optional trackingEvents?: VmapTrackingEvent[]

Contains the extracted VMAP tracking URLs associated with the ad break.

vastResponse?

optional vastResponse?: Promise<VastResponse>

The VAST response of the specified ad tag.

ImaAdBreakConfig

Interface

Extends

Extended by

Properties

discardAfterPlayback?

optional discardAfterPlayback?: boolean

Specifies whether ad breaks are discarded after they are played back, played over or tried to be played back but
failed due to some condition.
When set to false, ad breaks are played again when seeking back to a previous ad break position and never
discarded in any of the above cases.

The flag will be ignored when ImaAdTagConfig.passthroughMode
is set to ImaPassthroughMode.VastAndVmap

Default is true.

Inherited from

AdBreakConfig.discardAfterPlayback

fallbackTags?

optional fallbackTags?: AdTag[]

Defines a list of fallback ad tags which will be tried one after the other if the original ad tag does not
provide a valid response. The fallback ad tags need to have the same AdTagType as the main tag.

Inherited from

AdBreakConfig.fallbackTags

id

id: string

Unique identifier of the ad break. Used to be able to identify and discard the ad break dynamically.

Inherited from

AdBreakConfig.id

linearAdUiConfig?

optional linearAdUiConfig?: LinearAdUiConfig

Holds relevant information for the advertising UI.

Inherited from

AdBreakConfig.linearAdUiConfig

passthroughMode?

optional passthroughMode?: ImaPassthroughMode

Indicates which ad tags should be downloaded by the IMA SDK instead of by the Player. This can be helpful if
ad servers expect the IMA SDK to add some specific parameters to the request.

Inherited from

ImaAdTagConfig.passthroughMode

persistent?

optional persistent?: boolean

If set, the ad tag will be processed and rescheduled automatically when a new source is loaded.

Inherited from

AdBreakConfig.persistent

position

position: string

Defines when the ad break shall be started. Default is 'pre'.

Allowed values are:

  • 'pre': pre-roll ad
  • 'post': post-roll ad
  • fractional seconds: '10', '12.5' (mid-roll ad)
  • percentage of the entire video duration: '25%', '50%' (mid-roll ad)
  • timecode [hh:mm:ss.mmm]: '00:10:30.000', '01:00:00.000' (mid-roll ad)

Inherited from

AdBreakConfig.position

preloadOffset?

optional preloadOffset?: number

Specifies how many seconds before the ad break would start playing should the ad tag (and if possible the media
files of the resulting ad response) start pre-loading.
Default is 0.

Inherited from

AdBreakConfig.preloadOffset

replaceContentDuration?

optional replaceContentDuration?: number

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

Inherited from

AdBreakConfig.replaceContentDuration

tag

tag: AdTag

Defines the url and type of the ad manifest. If the tag is a VAST or VPAID manifest, then more specific
scheduling options can be defined in the AdBreakConfig.

Inherited from

AdBreakConfig.tag

ImaAdData

Interface

Holds various additional ad data. Refer to ImaAdData or
BitmovinAdData for more information on what
additional data is available when using our Google IMA SDK implementation or our native VAST implementation.

Extends

Properties

adDescription?

optional adDescription?: string

A longer description of the ad. Specified in InLine.Description in the VAST response.

Inherited from

VastAdData.adDescription

adSystem?

optional adSystem?: AdSystem

The ad system that returned the ad. Specified in InLine.AdSystem in the VAST response.

Inherited from

VastAdData.adSystem

adTitle?

optional adTitle?: string

A common name for the ad. Specified in InLine.AdTitle in the VAST response.

Inherited from

VastAdData.adTitle

advertiser?

optional advertiser?: Advertiser

The advertiser as defined by the ad serving party. Specified in InLine.Advertiser in the VAST response.

Inherited from

VastAdData.advertiser

apiFramework?

optional apiFramework?: string

Identifies the API needed to execute an interactive media file or communicate with the creative. Specified in
MediaFile.apiFramework for linear ads or NonLinear.apiFramework for non-linear ads in the VAST response.

Inherited from

VastAdData.apiFramework

bitrate?

optional bitrate?: number

The average bitrate of the progressive media file as defined in the VAST response.

Inherited from

VastAdData.bitrate

codec?

optional codec?: string

The codec used to encode the file which can take values as specified by https://tools.ietf.org/html/rfc4281.
Specified in MediaFile.codec in the VAST response.

Inherited from

VastAdData.codec

creative?

optional creative?: Creative

Contains various data about the Creative. Specified in InLine.Creative or Wrapper.Creative in the
VAST Response.

Inherited from

VastAdData.creative

dealId?

optional dealId?: string

The first deal ID present in the wrapper chain for the ad, starting from the top.

delivery?

optional delivery?: string

Either 'progressive' for progressive download protocols or 'streaming' for streaming protocols. Specified in
MediaFile.delivery in the VAST response.

Inherited from

VastAdData.delivery

maxBitrate?

optional maxBitrate?: number

The maximum bitrate of the streaming media file as defined in the VAST response.

Inherited from

VastAdData.maxBitrate

mediaFileId?

optional mediaFileId?: string

The media file ID. Specified in MediaFile.id in the VAST response.

Inherited from

VastAdData.mediaFileId

mimeType?

optional mimeType?: string

The MIME type of the media file or creative as defined in the VAST response.

Inherited from

VastAdData.mimeType

minBitrate?

optional minBitrate?: number

The minimum bitrate of the streaming media file as defined in the VAST response.

Inherited from

VastAdData.minBitrate

minSuggestedDuration?

optional minSuggestedDuration?: number

The minimum suggested duration that the creative should be displayed. Specified in NonLinear.minSuggestedDuration
in the VAST response.

Inherited from

VastAdData.minSuggestedDuration

pricing?

optional pricing?: AdPricing

Used to provide a value that represents a price that can be used by real-time bidding (RTB) systems. Specified
in Inline.Pricing in the VAST response.

Inherited from

VastAdData.pricing

survey?

optional survey?: AdSurvey

URI to any resource relating to an integrated survey. Specified in InLine.Survey in the VAST response.

Inherited from

VastAdData.survey

traffickingParameters?

optional traffickingParameters?: any https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/reference/js/google.ima.Ad#getTraffickingParameters

Only present if there are traffickingParameters.

wrapperAdIds?

optional wrapperAdIds?: string[]

The IDs of the Wrapper ads, starting at the InLine ad and ending at the outermost Wrapper ad. Contains an
empty array if there are no Wrapper ads.

Inherited from

VastAdData.wrapperAdIds

ImaAdTagConfig

Interface

Extends

Extended by

Properties

discardAfterPlayback?

optional discardAfterPlayback?: boolean

Specifies whether ad breaks are discarded after they are played back, played over or tried to be played back but
failed due to some condition.
When set to false, ad breaks are played again when seeking back to a previous ad break position and never
discarded in any of the above cases.

The flag will be ignored when ImaAdTagConfig.passthroughMode
is set to ImaPassthroughMode.VastAndVmap

Default is true.

Inherited from

AdTagConfig.discardAfterPlayback

fallbackTags?

optional fallbackTags?: AdTag[]

Defines a list of fallback ad tags which will be tried one after the other if the original ad tag does not
provide a valid response. The fallback ad tags need to have the same AdTagType as the main tag.

Inherited from

AdTagConfig.fallbackTags

linearAdUiConfig?

optional linearAdUiConfig?: LinearAdUiConfig

Holds relevant information for the advertising UI.

Inherited from

AdTagConfig.linearAdUiConfig

passthroughMode?

optional passthroughMode?: ImaPassthroughMode

Indicates which ad tags should be downloaded by the IMA SDK instead of by the Player. This can be helpful if
ad servers expect the IMA SDK to add some specific parameters to the request.

persistent?

optional persistent?: boolean

If set, the ad tag will be processed and rescheduled automatically when a new source is loaded.

Inherited from

AdTagConfig.persistent

replaceContentDuration?

optional replaceContentDuration?: number

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

Inherited from

AdTagConfig.replaceContentDuration

tag

tag: AdTag

Defines the url and type of the ad manifest. If the tag is a VAST or VPAID manifest, then more specific
scheduling options can be defined in the AdBreakConfig.

Inherited from

AdTagConfig.tag

ImaAdvertisingConfig

Interface

Single VAST tag example:

advertising: {
  adBreaks: [{
    tag: {
      url: 'http://your.ad.provider/vast-manifest.xml',
      type: 'vast'
    }
  }],
}

This is the most simple config example to play a single pre-roll ad.

Single VMAP tag example:

advertising: {
  adBreaks: [{
    tag: {
      url: 'http://your.ad.provider/vmap-manifest.xml',
      type: 'vmap'
    }
  }]
}

This config example will immediately download the VMAP manifest and schedule the resulting ad break(s) based on
information in the manifest.

This example plays all the ad breaks in the VMAP manifest based on timing information in the manifest itself,
while the three VAST ads are played as a pre-roll, mid-roll at 8 minutes and 30 seconds and a post-roll ad.
Additionally, the strategy chosen here will result in every seeked-over ad break being played. The latter two
manifests are loaded 5 seconds in advance.

Mixed example:

advertising: {
  adBreaks: [{
    tag: {
      url: 'http://your.ad.provider/vmap-manifest.xml',
      type: 'vmap'
    },
  }, {
    tag: {
      url: 'http://your.ad.provider/vast-manifest.xml',
      type: 'vast'
    },
    replaceContentDuration: 5,
    persistent: true,
    id: 'pre-roll-1',
    position: 'pre',
  }, {
    tag: {
      url: 'http://your.ad.provider/vast-manifest.xml',
      type: 'vast'
    },
    id: 'mid-roll-1',
    position: '00:08:30.000',
    preloadOffset: 5
  }, {
    tag: {
      url: 'http://your.ad.provider/vast-manifest.xml',
      type: 'vast'
    },
    persistent: true,
    id: 'post-roll-1',
    position: 'post',
    preloadOffset: 5
  }],
  strategy: {
    shouldLoadAdBreak: (adBreak) => true,
    shouldPlayAdBreak: (adBreak) => true,
    shouldPlaySkippedAdBreaks: (skipped, from, to) => skipped,
  }
}

Extends

Properties

adBreaks?

optional adBreaks?: AdConfig[]

Defines a collection of ad breaks which will be played at the specified position in each AdBreakConfig.

Inherited from

AdvertisingConfig.adBreaks

adContainer?

optional adContainer?: () => HTMLElement

Defines a function which returns a container that is used for displaying ads.

Returns

HTMLElement

Inherited from

AdvertisingConfig.adContainer

allowedUiElements?

optional allowedUiElements?: string[]

Defines an array of UI elements that should be displayed when an ad is active. Customizable UI elements are defined
at https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/reference/js/google.ima#.UiElements.

Setting this property to an empty array will not show the UI elements mentioned in the link above.

beforeInitialization?

optional beforeInitialization?: (sdkSettings) => void

Callback that provides access to the google.ima.ImaSdkSettings before any initialization happens.

Parameters

sdkSettings

any

Returns

void

companionAdContainers?

optional companionAdContainers?: () => HTMLElement[]

Defines a function which returns an array of containers for the ad module to fill with companion ads.

Returns

HTMLElement[]

Inherited from

AdvertisingConfig.companionAdContainers

disableStorageApi?

optional disableStorageApi?: boolean

When set to true, the ad module will be prohibited from using the browser's localStorage.

Defaults to disableStorageApi, if present, and falls back to false.

Since: v8.91.0

Inherited from

AdvertisingConfig.disableStorageApi

onAdContainerAvailable?

optional onAdContainerAvailable?: (adContainer) => void

Callback that provides access to the ad container.

Parameters

adContainer

HTMLElement

Returns

void

onAdsManagerAvailable?

optional onAdsManagerAvailable?: (adsManager) => void

Callback that provides access to the google.ima.AdsManager.

Parameters

adsManager

any

Returns

void

placeholders?

optional placeholders?: AdTagPlaceholders

List of placeholder strings that will be replaced in the ad manifest URL with the corresponding values.

Since: 8.1.0

Inherited from

AdvertisingConfig.placeholders

sdkUrl?

optional sdkUrl?: string

The URL of the Google IMA Framework.

Default URL: https://imasdk.googleapis.com/js/sdkloader/ima3.js

strategy?

optional strategy?: RestrictStrategy

Defines an object with two functions which will be called if an ad break is about to start or when ads are seeked
over. If this property is not set manually, then only the last ad that was seeked over will be played.

Inherited from

AdvertisingConfig.strategy

trackers?

optional trackers?: Trackers

Defines tracker configurations for the relevant packages such
as the Open measurement which will be loaded to provide
additional tracking information for ads.

Inherited from

AdvertisingConfig.trackers

vastLoadTimeout?

optional vastLoadTimeout?: number

Specifies the amount of milliseconds before the loading of a given ad manifest times out.
Default is 5000.

videoLoadTimeout?

optional videoLoadTimeout?: number

Specifies the amount of milliseconds before the loading of an ad from a given ad manifest times out.
Default is 8000.

Inherited from

AdvertisingConfig.videoLoadTimeout

withCredentials?

optional withCredentials?: boolean

Specifies whether to send credentials such as cookies or authorization headers along with the ad requests. The
server needs to explicitly accept them for CORS requests, otherwise the request will fail.
Default is true.

Inherited from

AdvertisingConfig.withCredentials

ImaModuleErrorCode

Enum

Google IMA Advertising Module error codes. These are in addition to the error codes found in
AdvertisingModuleErrorCode and VastErrorCode.

Enumeration Members

ADS_REQUEST_NETWORK_ERROR

ADS_REQUEST_NETWORK_ERROR: 1012

There was a problem requesting ads from the server.

ASSET_FALLBACK_FAILED

ASSET_FALLBACK_FAILED: 1021

There was an error with asset fallback.

AUTOPLAY_DISALLOWED

AUTOPLAY_DISALLOWED: 1205

The browser prevented playback initiated without user interaction.

FAILED_TO_REQUEST_ADS

FAILED_TO_REQUEST_ADS: 1005

There was a problem requesting ads from the server.

FAILED_TO_REQUEST_IMA_SDK

FAILED_TO_REQUEST_IMA_SDK: 103

There was a problem downloading the IMA SDK.

INVALID_AD_TAG

INVALID_AD_TAG: 1013

The ad tag url specified was invalid. It needs to be properly encoded.

INVALID_ARGUMENTS

INVALID_ARGUMENTS: 1101

Invalid arguments were provided to SDK methods.

STREAM_INITIALIZATION_FAILED

STREAM_INITIALIZATION_FAILED: 1020

There was an error with stream initialization during server side ad insertion.

UNKNOWN_AD_RESPONSE

UNKNOWN_AD_RESPONSE: 1010

The ad response was not understood and cannot be parsed.

UNSUPPORTED_LOCALE

UNSUPPORTED_LOCALE: 1011

Locale specified for the SDK is not supported.

VAST_ASSET_NOT_FOUND

VAST_ASSET_NOT_FOUND: 1007

No assets were found in the VAST ad response.

VAST_EMPTY_RESPONSE

VAST_EMPTY_RESPONSE: 1009

Empty VAST response.

VAST_NO_ADS_AFTER_WRAPPER

VAST_NO_ADS_AFTER_WRAPPER: 303

No Ads VAST response after one or more Wrappers.

ImaPassthroughMode

Enum

Enumeration Members

None

None: "none"

Ad tags will be downloaded by the Player in order to provide advanced features like preloading ad tags and
VAST 4.1 AdVerifications parsing.

Vast

Vast: "vast"

VAST tags will be downloaded by the IMA SDK, which will deactivate some features that are available with
None:

VastAndVmap

VastAndVmap: "vastandvmap"

In addition to Vast, VMAP tags will also be downloaded by the IMA SDK. This will lead to
the Advertising API being severely limited for VMAP tags:

  • Ad breaks will not be reflected via list
  • discardAdBreak will not be supported
  • downloadTiming will not be supported
  • VMAP tracking will not work
  • VAST ad tags can not be scheduled anymore after a VMAP tag has sucessfully been loaded by the IMA SDK
  • Consistent event order can not be guaranteed

This mode should only be used if absolutely necessary.

VastResponse

Interface

Properties

manifest?

optional manifest?: string

The VAST XML string that was returned by the ad server.
If Vast or VastAndVmap is used, this information will not be
available.

Updated 11 days ago

Did this page help you?

Updated 11 days ago

Did this page help you?