To discuss and provide feedback on our products, join the official Ad Manager Discord channel in the Google Advertising and Measurement Community server.

Interface AdsManager

AI-generated Key Takeaways

The AdsManager interface provides the public API for publishers to interact with and control the inner ad manager, extending ImaEventTarget.
It offers various methods to manage ads, including starting, pausing, resuming, skipping, collapsing, expanding, and stopping ad playback.
The AdsManager enables configuration for ad rendering settings and content playback, and provides ways to get information about ad playback, such as remaining time and skippable state.
Custom click tracking and playback can be enabled, and methods are available to check if they are being utilized.
Methods exist to add and remove event listeners, allowing the publisher to respond to various events triggered by the ad playback.

Provides the outer public API to the publisher and communicates with the inner instance of ads manager.

Methods
`addEventListener`	Adds a listener for ad events.
`collapse`	Collapse the current ad.
`configureAdsManager`	Sets required parameters for getting a reference to this AdManager from the AdsManagerLoaded event.
`destroy`	Removes ad assets loaded at runtime that need to be properly removed at the time of ad completion and stops the ad and all tracking.
`discardAdBreak`	If an ad break is currently playing, discard it and resume content.
`expand`	Expand the current ad.
`focus`	Puts the focus on the skip button, if present.
`getAdSkippableState`	Returns true if the ad can currently be skipped.
`getCuePoints`	Returns an array of offsets in seconds indicating when a scheduled ad break will play.
`getRemainingTime`	Get the remaining time of the current ad that is playing.
`getVolume`	Get the volume for the current ad.
`init`	Call init to initialize the ad experience on the ads manager.
`isCustomClickTrackingUsed`	Returns true if a custom click tracking element is being used for click tracking on the current ad.
`isCustomPlaybackUsed`	Returns true if a custom video element is being used to play the current ad.
`pause`	Pauses the current ad that is playing.
`removeEventListener`	Removes a listener for ad events.
`resize`	Resizes the current ad.
`resume`	Resumes the current ad that is loaded and paused.
`setVolume`	Set the volume for the current ad.
`skip`	Skips the current ad when `AdsManager.getAdSkippableState()` is true.
`start`	Start playing the ads.
`stop`	Stop playing the ads.
`updateAdsRenderingSettings`	Updates the ads rendering settings.

Methods

addEventListener

addEventListener(type: google.ima.AdEvent.Type, listener: ((event: AdEvent) => void),
              optCapture?: boolean,
              optHandlerScope?: object): void

Adds a listener for ad events.

Parameters
`type: google.ima.AdEvent.Type`	The type of event to listen for.
`listener: ((event: AdEvent) => void)`	A function called each time an event of this type occurs.
`Optional optCapture: boolean`	Deprecated and a no-op; retained for backward compatibility.
`Optional optHandlerScope: object`	Deprecated: Listener scope object. Use arrow functions or bind listener instead.

addEventListener(type: AD_ERROR, listener: ((event: AdErrorEvent) => void),
              optCapture?: boolean,
              optHandlerScope?: object): void

Adds a listener for ad error events.

Parameters
`type: AD_ERROR`	The type of event to listen for.
`listener: ((event: AdErrorEvent) => void)`	A function called each time an event of this type occurs.
`Optional optCapture: boolean`	Deprecated and a no-op; retained for backward compatibility.
`Optional optHandlerScope: object`	Deprecated: Listener scope object. Use arrow functions or bind listener instead.

collapse

collapse(): void

Collapse the current ad. For a non-linear ad, this hides the ad. For a VPAID ad, this sets the view mode to normal. For all other ad types, this is a no-op.

configureAdsManager

configureAdsManager(content: object, adsRenderingSettings?: AdsRenderingSettings): void

Sets required parameters for getting a reference to this AdManager from the AdsManagerLoaded event.

Parameters
`content: object`	Object that plays back publisher's content.
`Optional adsRenderingSettings: AdsRenderingSettings`	Optional settings to control the rendering of ads.

destroy

destroy(): void

Removes ad assets loaded at runtime that need to be properly removed at the time of ad completion and stops the ad and all tracking.

discardAdBreak

discardAdBreak(): void

If an ad break is currently playing, discard it and resume content. Otherwise, ignore the next scheduled ad break. For example, this can be called immediately after the ads manager loads to ignore a preroll without losing future midrolls or postrolls. This is a no-op unless the ad request returned a playlist or VMAP response.

expand

expand(): void

Expand the current ad. For a non-linear ad, this shows the ad. For a VPAID ad, this sets the view mode to fullscreen. For all other ad types, this is a no-op.

focus

focus(): void

Puts the focus on the skip button, if present. If not present, focus is put on interactive elements, including icons or interactive creatives.

getAdSkippableState

getAdSkippableState(): boolean

Returns true if the ad can currently be skipped. When this value changes, the AdsManager fires an AdEvent.SKIPPABLE_STATE_CHANGED event.

Returns
`boolean`	True if the ad can currently be skipped, false otherwise.

getCuePoints

getCuePoints(): number[]

Returns an array of offsets in seconds indicating when a scheduled ad break will play. A preroll is represented by 0, and a postroll is represented by -1. An empty array indicates the ad or ad pod has no schedule and can be played at any time.

Returns
`number[]`	List of time offsets in seconds.

getRemainingTime

getRemainingTime(): number

Get the remaining time of the current ad that is playing. If the ad is not loaded yet or has finished playing, the API would return -1.

Returns
`number`	Returns the time remaining for current ad. If the remaining time is undefined for the current ad (for example custom ads), the value returns -1.

getVolume

getVolume(): number

Get the volume for the current ad.

Returns
`number`	The volume of the current ad, from 0 (muted) to 1 (loudest).

init

init(width: number,
              height: number, viewMode?: unknown, videoElement?: HTMLVideoElement): void

Call init to initialize the ad experience on the ads manager.

Parameters
`width: number`	The chosen width of the ad.
`height: number`	The chosen height of the ad.
`Optional viewMode: unknown`	This value is ignored and can be omitted. Pass `undefined` if further arguments are passed.
`Optional videoElement: HTMLVideoElement`	The video element for custom playback. This video element overrides the one provided in the AdDisplayContainer constructor. Only use this property if absolutely necessary - otherwise we recommend specifying this video element while creating the AdDisplayContainer.

isCustomClickTrackingUsed

isCustomClickTrackingUsed(): boolean

Returns true if a custom click tracking element is being used for click tracking on the current ad. Custom click tracking is only used when an optional click tracking element is provided to the AdDisplayContainer, custom playback is used, and the current ad is not an AdSense/AdX ad.

Returns
`boolean`	Whether custom click tracking is used.

isCustomPlaybackUsed

isCustomPlaybackUsed(): boolean

Returns true if a custom video element is being used to play the current ad. Custom playback occurs when an optional video element is provided to the AdDisplayContainer on platforms where a custom video element would provide a more seamless ad viewing experience.

Returns
`boolean`	Whether custom playback is used.

pause

pause(): void

Pauses the current ad that is playing. This function will be no-op when a static overlay is being shown or if the ad is not loaded yet or is done playing.

removeEventListener

removeEventListener(type: google.ima.AdEvent.Type, listener: ((event: AdEvent) => void),
              optCapture?: boolean,
              optHandlerScope?: object): void

Removes a listener for ad events. The listener must be equal by reference to the one previously passed to addEventListener.

Parameters
`type: google.ima.AdEvent.Type`	The type of event for which to remove the listener.
`listener: ((event: AdEvent) => void)`	The function to remove as a listener.
`Optional optCapture: boolean`	Deprecated and a no-op; retained for backward compatibility.
`Optional optHandlerScope: object`	Deprecated: Listener scope object. Use arrow functions or bind listener instead.

removeEventListener(type: AD_ERROR, listener: ((event: AdErrorEvent) => void),
              optCapture?: boolean,
              optHandlerScope?: object): void

Removes a listener for ad error events. The listener function must be equal by reference to the one previously passed to addEventListener.

Parameters
`type: AD_ERROR`	The type of event for which to remove the listener.
`listener: ((event: AdErrorEvent) => void)`	The function to remove as a listener.
`Optional optCapture: boolean`	Deprecated and a no-op; retained for backward compatibility.
`Optional optHandlerScope: object`	Deprecated: Listener scope object. Use arrow functions or bind listener instead.

resize

resize(width: number, height: number,
              viewMode?: unknown): void

Resizes the current ad.

Parameters
`width: number`	New ad slot width.
`height: number`	New ad slot height.
`Optional viewMode: unknown`	This value is ignored and should be omitted.

resume

resume(): void

Resumes the current ad that is loaded and paused. This function will be no-op when a static overlay is being shown or if the ad is not loaded yet or is done playing.

setVolume

setVolume(volume: number): void

Set the volume for the current ad.

Parameters
`volume: number`	The volume to set, from 0 (muted) to 1 (loudest).

skip

skip(): void

Skips the current ad when AdsManager.getAdSkippableState() is true. When called under other circumstances, skip has no effect. After the skip is completed the AdsManager fires an AdEvent.SKIPPED event. AdsManager.skip() only skips ads if IMA does not render the 'Skip ad' button.

start

start(): void

Start playing the ads.

Developers must call AdDisplayContainer.initialize() first.

stop

stop(): void

Stop playing the ads. Calling this will get publisher back to the content.

updateAdsRenderingSettings

updateAdsRenderingSettings(adsRenderingSettings: AdsRenderingSettings): void

Updates the ads rendering settings. This should be used specifically for VMAP use cases between ad breaks when ads rendering settings such as bitrate need to be updated.

Parameters
`adsRenderingSettings: AdsRenderingSettings`	The updated ads rendering settings.