Advertising - IMA Module

google.ima.AdsManager

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

google.ima.AdsRequest

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

google.ima.ImaSdkSettings

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

ImaAdBreak

Ad break returned by the IMA advertising module.

Hierarchy

AdBreak
ImaAdBreakConfig

↳ ImaAdBreak

Properties

• 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

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

ImaAdBreakConfig.replaceContentDuration

scheduleTime

• scheduleTime: number

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

Inherited from

AdBreak.scheduleTime

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

Hierarchy

AdBreakConfig
ImaAdTagConfig

↳ ImaAdBreakConfig

↳↳ ImaAdBreak

Properties

discardAfterPlayback

• Optional discardAfterPlayback: boolean

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

Default is true.

Inherited from

ImaAdTagConfig.discardAfterPlayback

fallbackTags

• Optional fallbackTags: AdTag[]

Inherited from

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

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

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

ImaAdTagConfig.replaceContentDuration

ImaAdData

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.

Hierarchy

VastAdData

↳ ImaAdData

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

Hierarchy

AdTagConfig

↳ ImaAdTagConfig

↳↳ ImaAdBreakConfig

Properties

discardAfterPlayback

• Optional discardAfterPlayback: boolean

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

Default is true.

Inherited from

AdTagConfig.discardAfterPlayback

fallbackTags

• Optional fallbackTags: AdTag[]

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

ImaAdvertisingConfig

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,
  }
}

Hierarchy

AdvertisingConfig

↳ ImaAdvertisingConfig

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.

Type declaration

▸ (): HTMLElement

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: any) => void

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

Type declaration

▸ (sdkSettings): void

Parameters

Name	Type
`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.

Type declaration

▸ (): HTMLElement[]

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: HTMLElement) => void

Callback that provides access to the ad container.

Type declaration

▸ (adContainer): void

Parameters

Name	Type
`adContainer`	`HTMLElement`

Returns

void

onAdsManagerAvailable

• Optional onAdsManagerAvailable: (adsManager: any) => void

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

Type declaration

▸ (adsManager): void

Parameters

Name	Type
`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

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

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:

preloadOffset will not work
manifest and verifications will not be available
downloadTiming will not be as accurate (higher)

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

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.