Google IMA HTML5 SDK APIs

Interface google.ima.Ad

Methods

getAdId, getAdPodInfo, getAdSystem, getCompanionAds, getContentType, getDescription, getDuration, getHeight, getMinSuggestedDuration, getTitle, getUiElements, getWidth, getWrapperAdIds, getWrapperAdSystems, isLinear

An ad class that's extended by classes representing different ad types.

`getAdId()`

Ad ID is used to synchronize master ad and companion ads.

Returns string: The ID of the ad, or the empty string if this information is unavailable.

`getAdPodInfo()`

Returns the ad's pod information.

Returns google.ima.AdPodInfo: The ad's pod information.

`getAdSystem()`

The source ad server information included in the ad response.

Returns string: The source ad server of the ad, or the empty string if this information is unavailable.

`getCompanionAds(adSlotWidth, adSlotHeight, opt_settings)`

Gets the companion ads for this ad based on companion ad slot size. Optionally, advanced selection settings are accepted. Note that this method will only return non-empty array for ad instances acquired on or after STARTED event. Specifically, ads from the LOADED event will return an empty array.

Returns Array: Array of companion ads that matches the settings and the slot size.

Parameter	Type	Description
`adSlotWidth`	`number`	Width of the companion ad slot.
`adSlotHeight`	`number`	Height of the companion ad slot.
`opt_settings`	`google.ima.CompanionAdSelectionSettings`	The selection settings for companion ads.

`getContentType()`

Returns the content type of the currently selected creative, or empty string if no creative is selected or the content type is unavailable. For linear ads, the content type is only going to be available after the START event, when the media file is selected.

Returns string: The content type, empty string if not available.

`getDescription()`

Returns the description of this ad from the VAST response.

Returns string: The description, empty if not specified.

`getDuration()`

Returns the duration of the selected creative, or -1 for non-linear creatives.

Returns number: The selected creative duration in seconds, -1 if non-linear.

`getHeight()`

Returns the height of the selected non-linear creative.

Returns number: The height of the selected non-linear creative or 0 for a linear creative.

`getMinSuggestedDuration()`

Returns the minimum suggested duration in seconds that the nonlinear creative should be displayed. Returns -2 if the minimum suggested duration is unknown. For linear creative it returns the entire duration of the ad.

Returns number: The minimum suggested duration in seconds that a creative should be displayed.

`getTitle()`

Returns the title of this ad from the VAST response.

Returns string: The title, empty if not specified.

`getUiElements()`

Returns the UI elements that are being displayed when this ad is played. Refer to UiElements for possible elements of the array returned.

Returns Array.<string>: The UI elements being displayed.

`getWidth()`

Returns the width of the selected creative.

Returns number: The width of the selected non-linear creative or 0 for a linear creative.

`getWrapperAdIds()`

Ad IDs used for wrapper ads. The ids returned begin with the first wrapper ad and continue to each wrapped ad recursively.

Returns Array.<string>: The IDs of the ads, starting with the first wrapper ad or an empty array if there are no wrapper ads.

`getWrapperAdSystems()`

Ad systems used for wrapper ads. The ad systems returned begin with the first wrapper ad and continue to each wrapper ad recursively.

Returns Array.<string>: The ad system of the ads, starting with the first wrapper ad or an empty array if there are no wrapper ads.

`isLinear()`

Indicates whether the ad’s current mode of operation is linear or non-linear. If the value is true, it indicates that the ad is in linear playback mode; if false, it indicates non-linear mode. The player checks the linear property and updates its state according to the details of the ad placement. While the ad is in linear mode, the player pauses the content video. If linear is true initially, and the ad is a pre-roll (defined externally), the player may choose to delay loading the content video until near the end of the ad playback.

Returns boolean: True if the ad is linear, false otherwise.

Class google.ima.AdDisplayContainer

Methods

destroy, initialize

This class represents a container for displaying ads. The SDK will automatically create structures inside the containerElement parameter to house video and overlay ads.

When an instance of this class is created, it creates an IFRAME in the containerElement and loads the SDK core. This IFRAME must be preserved in order for the SDK to function properly. Once all ads have been played and the SDK is no longer needed, use the destroy() method to unload the SDK.

The containerElement parameter must be an element that is part of the DOM. It is necessary to correctly position the containerElement in order for the ads to be displayed correctly. It is recommended to position it above the content video player and size it to cover the whole video player. Please refer to the SDK documentation for details about recommended implementations.

Note for use on iOS (iPhone/iPad) and Android: Due to platform limitations, it is necessary to call the initialize() method in code that was directly invoked by a user action (e.g. a click/tap).

Constructor:

Parameter	Type	Description
`containerElement`	`Element`	The element to display the ads in. The element must be inserted into the DOM before creating ima.AdDisplayContainer.
`opt_videoElement`	`HTMLVideoElement`	Specifies the alternative video ad playback element. We recommend always passing in your content video player. Refer to Custom Ad Playback for more information.
`opt_clickTrackingElement`	`Element`	Specifies the alternative video ad click element. Leave this null to let the SDK handle clicks. Even if supplied, the SDK will only use the custom click tracking element when non-AdSense/AdX creatives are displayed in environments that do not support UI elements overlaying a video player (e.g. iPhone or pre-4.0 Android). The custom click tracking element should never be rendered over the video player because it can intercept clicks to UI elements that the SDK renders. Also note that the SDK will not modify the visibility of the custom click tracking element. This means that if a custom click tracking element is supplied, it must be properly displayed when the linear ad is played. You can check `ima.AdsManager.isCustomClickTrackingUsed` when the `google.ima.AdEvent.Type.STARTED` event is fired to determine whether or not to display your custom click tracking element. If appropriate for your UI, you should hide the click tracking element when the `google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED` event fires.

`destroy()`

Destroys internal state and previously created DOM elements. The IMA SDK will be unloaded and no further calls to any APIs should be made.

`initialize()`

Initializes the video playback. On mobile platforms, including iOS and Android browsers, first interaction with video playback is only allowed within a user action (a click or tap) to prevent unexpected bandwidth costs. Call this method as a direct result of a user action before starting the ad playback. This method has no effect on desktop platforms and when custom video playback is used.

Class google.ima.AdError

Methods

getErrorCode, getInnerError, getMessage, getType, getVastErrorCode, toString

AdError surfaces information to the user about whether a failure occurred during ad loading or playing. The errorType accessor provides information about whether the error occurred during ad loading or ad playing.

`getErrorCode()`

Returns number: The error code, as defined in google.ima.AdError.ErrorCode.

`getInnerError()`

Returns the native Error that caused this one.

Returns Error: Inner error that occurred during processing, or null if this information is unavailable. This may return null if the error that caused this one is not available.

`getMessage()`

Returns string: The message for this error.

`getType()`

Returns string: The type of this error, as defined in google.ima.AdError.Type.

`getVastErrorCode()`

Returns number: If VAST error code is available, returns it, otherwise returns ima.AdError.ErrorCode.UNKNOWN_ERROR.

`toString()`

Enum google.ima.AdError.ErrorCode

Fields

COMPANION_AD_LOADING_FAILED, COMPANION_REQUIRED_ERROR, FAILED_TO_REQUEST_ADS, INVALID_ADX_EXTENSION, INVALID_ARGUMENTS, NONLINEAR_DIMENSIONS_ERROR, OVERLAY_AD_LOADING_FAILED, OVERLAY_AD_PLAYING_FAILED, UNKNOWN_AD_RESPONSE, UNKNOWN_ERROR, UNSUPPORTED_LOCALE, VAST_ASSET_NOT_FOUND, VAST_EMPTY_RESPONSE, VAST_LINEAR_ASSET_MISMATCH, VAST_LOAD_TIMEOUT, VAST_MALFORMED_RESPONSE, VAST_MEDIA_LOAD_TIMEOUT, VAST_NO_ADS_AFTER_WRAPPER, VAST_NONLINEAR_ASSET_MISMATCH, VAST_SCHEMA_VALIDATION_ERROR, VAST_TOO_MANY_REDIRECTS, VAST_TRAFFICKING_ERROR, VAST_UNEXPECTED_DURATION_ERROR, VAST_UNEXPECTED_LINEARITY, VAST_UNSUPPORTED_VERSION, VAST_WRAPPER_ERROR, VIDEO_PLAY_ERROR

The possible error codes raised while loading or playing ads.

Values

Value	Description
`COMPANION_AD_LOADING_FAILED`	A companion ad failed to load or render.
`COMPANION_REQUIRED_ERROR`	Unable to display one or more required companions. The master ad is discarded since the required companions could not be displayed.
`FAILED_TO_REQUEST_ADS`	There was a problem requesting ads from the server.
`INVALID_ADX_EXTENSION`	An invalid AdX extension was found.
`INVALID_ARGUMENTS`	Invalid arguments were provided to SDK methods.
`NONLINEAR_DIMENSIONS_ERROR`	Unable to display NonLinear ad because creative dimensions do not align with creative display area (i.e. creative dimension too large).
`OVERLAY_AD_LOADING_FAILED`	An overlay ad failed to load.
`OVERLAY_AD_PLAYING_FAILED`	An overlay ad failed to render.
`UNKNOWN_AD_RESPONSE`	The ad response was not understood and cannot be parsed.
`UNKNOWN_ERROR`	An unexpected error occurred and the cause is not known. Refer to the inner error for more information.
`UNSUPPORTED_LOCALE`	Locale specified for the SDK is not supported.
`VAST_ASSET_NOT_FOUND`	No assets were found in the VAST ad response.
`VAST_EMPTY_RESPONSE`	Empty VAST response.
`VAST_LINEAR_ASSET_MISMATCH`	Assets were found in the VAST ad response for linear ad, but none of them matched the video player's capabilities.
`VAST_LOAD_TIMEOUT`	The VAST URI provided, or a VAST URI provided in a subsequent Wrapper element, was either unavailable or reached a timeout, as defined by the video player. The timeout is 8 seconds for initial VAST requests and 4 seconds for each subsequent Wrapper.
`VAST_MALFORMED_RESPONSE`	The ad response was not recognized as a valid VAST ad.
`VAST_MEDIA_LOAD_TIMEOUT`	Failed to load media assets from a VAST response. The default timeout for media loading is 15 seconds.
`VAST_NO_ADS_AFTER_WRAPPER`	No Ads VAST response after one or more Wrappers.
`VAST_NONLINEAR_ASSET_MISMATCH`	Assets were found in the VAST ad response for nonlinear ad, but none of them matched the video player's capabilities.
`VAST_SCHEMA_VALIDATION_ERROR`	VAST schema validation error.
`VAST_TOO_MANY_REDIRECTS`	The maximum number of VAST wrapper redirects has been reached.
`VAST_TRAFFICKING_ERROR`	Trafficking error. Video player received an ad type that it was not expecting and/or cannot display.
`VAST_UNEXPECTED_DURATION_ERROR`	VAST duration is different from the actual media file duration.
`VAST_UNEXPECTED_LINEARITY`	Ad linearity is different from what the video player is expecting.
`VAST_UNSUPPORTED_VERSION`	VAST schema validation error.
`VAST_WRAPPER_ERROR`	General VAST wrapper error.
`VIDEO_PLAY_ERROR`	There was an error playing the video ad.

Enum google.ima.AdError.Type

Fields

AD_LOAD, AD_PLAY

The possible error types for ad loading and playing.

Values

Value	Description
`AD_LOAD`	Indicates that the error was encountered when the ad was being loaded. Possible causes: there was no response from the ad server, malformed ad response was returned, or ad request parameters failed to pass validation.
`AD_PLAY`	Indicates that the error was encountered after the ad loaded, during ad play. Possible causes: ad assets could not be loaded, etc.

Class google.ima.AdErrorEvent

Methods

getError, getUserRequestContext

This event is raised when an error occurs when loading an ad from the Google or DoubleClick servers. The types on which you can register for the event are AdsLoader and AdsManager.

`getError()`

Returns google.ima.AdError: The AdError that caused this event.

`getUserRequestContext()`

During ads load request it is possible to provide an object that is available once the ads load is complete or fails. One possible use case: relate ads response to a specific request and use user request content object as the key for identifying the response. If an error occurred during ads load, you can find out which request caused this failure.

Returns Object: that was provided during ads request.

Enum google.ima.AdErrorEvent.Type

Fields

AD_ERROR

Types of AdErrorEvents

Values

Value	Description
`AD_ERROR`	Fired when an error occurred while the ad was loading or playing.

Class google.ima.AdEvent

Methods

getAd, getAdData

This event type is raised by the ad as a notification when the ad state changes and when users interact with the ad. For example, when the ad starts playing, is clicked on, etc. You can register for the various state changed events on AdsManager.

`getAd()`

Get the current ad that is playing or just played.

Returns google.ima.Ad: The ad associated with the event, or null if there is no relevant ad.

`getAdData()`

Allows extra data to be passed from the ad.

Example:


if (event.type == google.ima.AdEvent.Type.LOG) {
  var adData = event.getAdData();
  if (adData['adError']) {
    console.log('Non-fatal error occurred: ' +
        adData['adError'].getMessage();
  }
}

Returns Object: Extra data for the event. Log events raised for error carry object of type 'google.ima.AdError' which can be accessed using 'adError' key.

Enum google.ima.AdEvent.Type

Fields

AD_BREAK_READY, AD_METADATA, ALL_ADS_COMPLETED, CLICK, COMPLETE, CONTENT_PAUSE_REQUESTED, CONTENT_RESUME_REQUESTED, FIRST_QUARTILE, IMPRESSION, LOADED, LOG, MIDPOINT, PAUSED, RESUMED, SKIPPABLE_STATE_CHANGED, SKIPPED, STARTED, THIRD_QUARTILE, USER_CLOSE, VOLUME_CHANGED, VOLUME_MUTED

Types of AdEvents

Values

Value	Description
`AD_BREAK_READY`	Fired when an ad rule or a VMAP ad break would have played if autoPlayAdBreaks is false.
`AD_METADATA`	Fired when an ads list is loaded.
`ALL_ADS_COMPLETED`	Fired when the ads manager is done playing all the ads.
`CLICK`	Fired when the ad is clicked.
`COMPLETE`	Fired when the ad completes playing.
`CONTENT_PAUSE_REQUESTED`	Fired when content should be paused. This usually happens right before an ad is about to cover the content.
`CONTENT_RESUME_REQUESTED`	Fired when content should be resumed. This usually happens when an ad finishes or collapses.
`FIRST_QUARTILE`	Fired when the ad playhead crosses first quartile.
`IMPRESSION`	Fired when the impression URL has been pinged.
`LOADED`	Fired when ad data is available.
`LOG`	Fired when a non-fatal error is encountered. The user need not take any action since the SDK will continue with the same or next ad playback depending on the error situation.
`MIDPOINT`	Fired when the ad playhead crosses midpoint.
`PAUSED`	Fired when the ad is paused.
`RESUMED`	Fired when the ad is resumed.
`SKIPPABLE_STATE_CHANGED`	Fired when the displayed ads skippable state is changed.
`SKIPPED`	Fired when the ad is skipped by the user.
`STARTED`	Fired when the ad starts playing.
`THIRD_QUARTILE`	Fired when the ad playhead crosses third quartile.
`USER_CLOSE`	Fired when the ad is closed by the user.
`VOLUME_CHANGED`	Fired when the ad volume has changed.
`VOLUME_MUTED`	Fired when the ad volume has been muted.

Interface google.ima.AdPodInfo

Methods

getAdPosition, getIsBumper, getMaxDuration, getPodIndex, getTimeOffset, getTotalAds

An ad may be part of a pod of ads. This object exposes metadata related to that pod, such as the number of ads in the pod and ad position within the pod.

The getTotalAds API contained within this object is often correct, but in certain scenarios, it represents the SDK's best guess. See that method's documentation for more information.

`getAdPosition()`

Returns the position of the ad.

Returns number: The position of the ad within the pod. The value returned is one-based, i.e. 1 of 2, 2 of 2, etc.

`getIsBumper()`

Returns true if the ad is a bumper ad. Bumper ads are short linear ads that can indicate to a user when the user is entering into or exiting from an ad break.

Returns boolean: Whether the ad is a bumper ad.

`getMaxDuration()`

The maximum duration of the pod in seconds. For unknown duration, -1 is returned.

Returns number: The maximum duration of the ads in this pod in seconds.

`getPodIndex()`

Returns the index of the ad pod.

For preroll pod, 0 is returned. For midrolls, 1, 2, ... N is returned. For postroll, -1 is returned.

Defaults to 0 if this ad is not part of a pod, or the pod is not part of an ad playlist.

Returns number: The index of the pod in the ad playlist.

`getTimeOffset()`

Returns the content time offset at which the current ad pod was scheduled.

For preroll pod, 0 is returned. For midrolls, the scheduled time is returned. For postroll, -1 is returned.

Defaults to 0 if this ad is not part of a pod, or the pod is not part of an ad playlist.

Returns number: The content time offset for the current ad pod.

`getTotalAds()`

The total number of ads contained within this pod, including bumpers. Bumper ads are short linear ads that can indicate to a user when the user is entering into or exiting from an ad break.

Defaults to 1 if this ad is not part of a pod.

In certain scenarios, the SDK does not know for sure how many ads are contained within this ad pod. These scenarios include ad pods, which are multiple ads within a single ad tag. In these scenarios, the first few AdEvents fired (AD_METADATA, LOADED, etc.) may have just the total number of ad tags from the playlist response. We recommend using the STARTED event as the event in which publishers pull information from this object and update the visual elements of the player, if any.

Returns number: Total number of ads in the pod.

Class google.ima.AdsLoader

Methods

contentComplete, destroy, getSettings, requestAds

AdsLoader allows clients to request ads from ad servers. To do so, users must register for the AdsManagerLoadedEvent event and then request ads.

Constructor:

Parameter	Type	Description
`container`	`google.ima.AdDisplayContainer`	The display container for ads.

`contentComplete()`

Signals to the SDK that the content is finished. This will allow the SDK to play post-roll ads, if any are loaded via ad rules.

`destroy()`

Cleans up the internal state.

`getSettings()`

Returns the IMA SDK settings instance. To change the settings, just call the methods on the instance. The changes will apply for all the ad requests made with this ads loader.

Returns google.ima.ImaSdkSettings: The settings instance.

`requestAds(adsRequest, opt_userRequestContext)`

Request ads from a server.

Parameter	Type	Description
`adsRequest`	`google.ima.AdsRequest`	AdsRequest instance containing data for the ads request.
`opt_userRequestContext`	`Object`	User-provided object that is associated with the ads request. It can be retrieved when the ads are loaded.

Interface google.ima.AdsManager

Methods

collapse, destroy, expand, getAdSkippableState, getCuePoints, getRemainingTime, getVolume, init, isCustomClickTrackingUsed, isCustomPlaybackUsed, pause, resize, resume, setVolume, skip, start, stop

This class is responsible for playing ads.

`collapse()`

Collapse the current ad. This is no-op for HTML5 SDK.

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

`expand()`

Expand the current ad. This is no-op for HTML5 SDK.

`getAdSkippableState()`

Returns true if the ad can currently be skipped. For ads where Ad.isSkippable is false, this always returns false. 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()`

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 Array.<number>: List of time offsets in seconds.

`getRemainingTime()`

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()`

Get the volume for the current ad.

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

`init(width, height, viewMode)`

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

Parameter	Type	Description
`width`	`number`	The desired width of the ad.
`height`	`number`	The desired height of the ad.
`viewMode`	`google.ima.ViewMode`	The desired view mode.

`isCustomClickTrackingUsed()`

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()`

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()`

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.

`resize(width, height, viewMode)`

Resizes the current ad.

Parameter	Type	Description
`width`	`number`	New ad slot width.
`height`	`number`	New ad slot height.
`viewMode`	`google.ima.ViewMode`	The new view mode.

`resume()`

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(volume)`

Set the volume for the current ad.

Parameter	Type	Description
`volume`	`number`	The volume to set, from 0 (muted) to 1 (loudest).

`skip()`

Skips the current ad when Ad.isSkippable is true. When called under other circumstances, skip has no effect. After the skip is completed the AdsManager fires an AdEvent.SKIPPED event.

`start()`

Start playing the ads.

`stop()`

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

Class google.ima.AdsManagerLoadedEvent

Methods

getAdsManager, getUserRequestContext

This event is raised when ads are successfully loaded from the Google or DoubleClick ad servers via an AdsLoader. You can register for this event on AdsLoader.

`getAdsManager(contentPlayback, adsRenderingSettings)`

After ads are loaded from the Google or DoubleClick ad servers, the publisher needs to play these ads either in their own video player or in the Google-provided video player. This method returns an AdsManager object. The AdsManager supports playing ads and allows the publisher to subscribe to various events during ad playback.

Returns google.ima.AdsManager: AdsManager that manages and plays ads.

Parameter	Type	Description
`contentPlayback`	`Object`	Player that plays back publisher's content. This must be an object that contains the property `currentTime`, which allows the SDK to query playhead position to properly display midrolls in case ad server responds with an ad rule, and the `duration` property. The HMTL5 video element fulfills these requirements. You may optionally implement your own playhead tracker, as long as it fulfills the above requirements.
`adsRenderingSettings`	`google.ima.AdsRenderingSettings`	Optional settings to control the rendering of ads.

`getUserRequestContext()`

Returns Object: During ads load request it is possible to provide an object that is available once the ads load is complete. One possible use case: relate ads response to a specific request and use user request content object as a key for identifying the response.

Enum google.ima.AdsManagerLoadedEvent.Type

Fields

ADS_MANAGER_LOADED

Types of AdsManagerLoadedEvents.

Values

Value	Description
`ADS_MANAGER_LOADED`	Fired when the ads have been loaded and an AdsManager is available.

Class google.ima.AdsRenderingSettings

Fields

AUTO_SCALE, autoAlign, bitrate, loadVideoTimeout, mimeTypes, restoreCustomPlaybackStateOnAdBreakComplete, uiElements, useShareButton, useStyledNonLinearAds

Defines parameters that control the rendering of ads.

Properties

Name	Type	Description
`AUTO_SCALE`	`number`	Constant value to indicate that the SDK's width or height should fill the containing div that it's within.
`autoAlign`	`boolean`	Set to false if you wish to have fine grained control over the positioning of all non-linear ads. If this value is true, the ad is positioned in the bottom center. If this value is false, the ad is positioned in the top left corner. The default value is true.
`bitrate`	`number`	Maximum recommended bitrate. The value is in kbit/s. SDK will pick media with bitrate below the specified max, or the closest bitrate if there is no media with lower bitrate found. Default value, -1, means the bitrate will be selected by the SDK.
`loadVideoTimeout`	`number`	Timeout (in milliseconds) when loading a video ad media file. If loading takes longer than this timeout, the ad playback is canceled and the next ad in the pod plays, if available. Use -1 for the default of 15 seconds.
`mimeTypes`	`Array.<string>`	If specified, the SDK will give priority to media that matches the MIME type(s) specified in the list and exclude media that does not match the specified MIME type(s). The format is a list of strings, e.g. [ 'video/mp4', 'video/webm', ... ] If not specified, the SDK will pick the media based on player capabilities.
`restoreCustomPlaybackStateOnAdBreakComplete`		Specifies whether or not the SDK should restore the custom playback state after an ad break completes. This is setting is used primarily when the publisher passes in its content player to use for custom ad playback.
`uiElements`	`Array.<string>`	Specifies whether the UI elements that should be displayed. Some of the elements in this array may be ignored for AdSense and AdX ads.
`useShareButton`	`boolean`	Render the "Share" button for the video ad UX.
`useStyledNonLinearAds`	`boolean`	Render non-linear ads with a close and recall button.

Class google.ima.AdsRequest

Fields

adsResponse, adTagUrl, linearAdSlotHeight, linearAdSlotWidth, nonLinearAdSlotHeight, nonLinearAdSlotWidth

Methods

setAdWillAutoPlay

A class for specifying properties of the ad request.

Properties

Name	Type	Description
`adsResponse`	`string`	Specifies a VAST 2.0 document to be used as the ads response instead of making a request via an ad tag url. This can be useful for debugging and other situations where a VAST response is already available. This parameter is optional.
`adTagUrl`	`string`	Specifies the ad tag url that is requested from the ad server. This parameter is required.
`linearAdSlotHeight`	`number`	Specifies the height of the rectangular area within which a linear ad is displayed. This value is used as one of the criteria for ads selection. This value does not need to match actual ad's height. This parameter is required.
`linearAdSlotWidth`	`number`	Specifies the width of the rectangular area within which a linear ad is displayed. This value is used as one of the criteria for ads selection. This value does not need to match actual ad's width. This parameter is required.
`nonLinearAdSlotHeight`	`number`	Specifies the height of the rectangular area within which a non linear ad is displayed. This value is used as one of the criteria for ads selection. This value does not need to match actual ad's height. This parameter is required.
`nonLinearAdSlotWidth`	`number`	Specifies the width of the rectangular area within which a non linear ad is displayed. This value is used as one of the criteria for ads selection. This value does not need to match actual ad's width. This parameter is required.

`setAdWillAutoPlay(autoPlay)`

Notifies the SDK whether the player intends to start the content and ad in response to a user action or whether it will be automatically played. Changing this setting will have no impact on ad playback.

Parameter	Type	Description
`autoPlay`	`boolean`	Whether the content and the ad will be autoplayed or whether it will be started by a user action.

Interface google.ima.CompanionAd

Methods

getAdSlotId, getContent, getContentType, getHeight, getWidth

A companion ad class that is extended by companion ads of different ad types.

`getAdSlotId()`

Returns string: Returns the ad slot id for this companion.

`getContent()`

Returns the HTML content for the companion ad that can be added to the publisher page.

Returns string: The HTML content.

`getContentType()`

Returns string: The content type of the Companion Ad. This may return null if the content type is not known (such as in the case of a VAST HTMLResource or IFrameResource).

`getHeight()`

Returns number: Returns the height of the companion in pixels.

`getWidth()`

Returns number: Returns the width of the companion in pixels.

Class google.ima.CompanionAdSelectionSettings

Fields

adSlotIds, creativeType, nearMatchPercent, resourceType, sizeCriteria

CompanionAdSelectionSettings object is used to define the selection criteria when calling the ima.Ad.getCompanionAds function.

Properties

Name	Type	Description
`adSlotIds`	`Array.<string>`	The companion ad slot ids to be used for matching set by the user.
`creativeType`	`google.ima.CompanionAdSelectionSettings.CreativeType`	Creative type setting set by the user.
`nearMatchPercent`	`number`	The near fit percent set by the user.
`resourceType`	`google.ima.CompanionAdSelectionSettings.ResourceType`	Resource type setting set by the user.
`sizeCriteria`	`google.ima.CompanionAdSelectionSettings.SizeCriteria`	Size criteria setting set by the user.

Enum google.ima.CompanionAdSelectionSettings.CreativeType

Fields

ALL, FLASH, IMAGE

Available choices for creative type of a companion ad. The user can specify any of these choices as a criterion for selecting companion ads.

Values

Value	Description
`ALL`	Specifies all creative types.
`FLASH`	Specifies Flash creatives.
`IMAGE`	Specifies image creatives (such as JPEG, PNG, GIF, etc).

Enum google.ima.CompanionAdSelectionSettings.ResourceType

Fields

ALL, HTML, IFRAME, STATIC

Available choices for resource type of a companion ad. The user can specify any of these choices as a criterion for selecting companion ads.

Values

Value	Description
`ALL`	Specifies that the resource can be any type of resource.
`HTML`	Specifies that the resource should be an HTML snippet.
`IFRAME`	Specifies that the resource should be a URL that should be used as the source of an `iframe`.
`STATIC`	Specifies that the resource should be a static file (usually the URL of an image of SWF).

Enum google.ima.CompanionAdSelectionSettings.SizeCriteria

Fields

IGNORE, SELECT_EXACT_MATCH, SELECT_NEAR_MATCH

Available choices for size selection criteria. The user can specify any of these choices for selecting companion ads.

Values

Value	Description
`IGNORE`	Specifies that size should be ignored when choosing companions.
`SELECT_EXACT_MATCH`	Specifies that only companions that match the size of the companion ad slot exactly should be chosen.
`SELECT_NEAR_MATCH`	Specifies that any companion close to the size of the companion ad slot should be chosen.

Class google.ima.ImaSdkSettings

Methods

getCompanionBackfill, getLocale, getNumRedirects, getPlayerType, getPlayerVersion, getPpid, setAutoPlayAdBreaks, setCompanionBackfill, setLocale, setNumRedirects, setPlayerType, setPlayerVersion, setPpid, setVpaidAllowed, setVpaidMode

This class contains SDK-wide settings.

`getCompanionBackfill()`

Returns the current companion backfill mode.

Returns google.ima.ImaSdkSettings.CompanionBackfillMode: The current value.

`getLocale()`

Returns the publisher provided locale.

Returns string: Publisher provided locale.

`getNumRedirects()`

Returns the maximum number of redirects for subsequent redirects will be denied.

Returns number: the maximum number of redirects.

`getPlayerType()`

Returns the partner provided player type.

Returns string: Partner player type.

`getPlayerVersion()`

Returns the partner provided player version.

Returns string: Partner player version.

`getPpid()`

Returns the publisher provided id.

Returns string: publisher provided id.

`setAutoPlayAdBreaks(autoPlayAdBreaks)`

Sets whether VMAP and ad rules ad breaks are automatically played

Parameter	Type	Description
`autoPlayAdBreaks`	`boolean`	Whether to autoPlay the ad breaks.

`setCompanionBackfill(mode)`

Sets the companion backfill mode. Please see the various modes available in google.ima.ImaSdkSettings.CompanionBackfillMode.

The default mode is ima.ImaSdkSettings.CompanionBackfillMode.ALWAYS.

Parameter	Type	Description
`mode`	`google.ima.ImaSdkSettings.CompanionBackfillMode`	The desired companion backfill mode.

`setLocale(locale)`

Sets the publisher provided locale. Must be called before creating AdsLoader or AdDisplayContainer.

Parameter	Type	Description
`locale`	`string`	Publisher provided locale. UI elements will display in the specified language. May be any ISO 639-1 (two-letter) or ISO 639-2 (three-letter) code. Please refer here for a list of valid codes: http://www.loc.gov/standards/iso639-2/php/English_list.php.

`setNumRedirects(numRedirects)`

Specifies the maximum number of redirects before the subsequent redirects will be denied, and the ad load aborted. The number of redirects directly affects latency and thus user experience. This applies to all VAST wrapper ads.

Parameter	Type	Description
`numRedirects`	`number`	the maximum number of redirects.

`setPlayerType(playerType)`

Sets the partner provided player type. This setting should be used to specify the name of the player being integrated with the SDK. Player type greater than 20 characters will be truncated. The player type specified should be short and unique. This is an optional setting used to improve SDK usability by tracking player types.

Example:


ima.setting.setPlayerType('google/gmf-player');

Parameter	Type	Description
`playerType`	`string`	The type of the partner player.

`setPlayerVersion(playerVersion)`

Sets the partner provided player version. This setting should be used to specify the version of the partner player being integrated with the SDK. Player versions greater than 20 characters will be truncated. This is an optional setting used to improve SDK usability by tracking player version.

Example:


ima.setting.setPlayerVersion('1.0.0');

Parameter	Type	Description
`playerVersion`	`string`	The version of the partner player.

`setPpid(ppid)`

Sets the publisher provided id.

Parameter	Type	Description
`ppid`	`string`	publisher provided id.

`setVpaidAllowed(allowVpaid)`

Deprecated. Please use setVpaidMode. Sets whether VPAID creatives are allowed.

Parameter	Type	Description
`allowVpaid`	`boolean`	Whether to allow VPAID creatives.

`setVpaidMode(vpaidMode)`

Sets VPAID playback mode.

Parameter	Type	Description
`vpaidMode`	`google.ima.ImaSdkSettings.VpaidMode`	Sets how VPAID ads will be played. Default is to not allow VPAID ads.

Enum google.ima.ImaSdkSettings.CompanionBackfillMode

Defines a set of constants for the companion backfill setting. This setting indicates whether companions should be backfilled in various scenarios.

If the value is ALWAYS, companion backfill will be attempted in all situations, even when there is no master ad returned.

If the value is ON_MASTER_AD, companion backfill will be attempted if there is a master ad with fewer companions than there are companion slots. The missing companions will be backfilled.

The default value is ALWAYS.

Note that client-side companion backfill requires tagging your companions properly with a Google Publisher Tag (GPT). To enable backfill, the following changes to standard GPT setup are necessary:

...
var slot1 = googletag.defineSlot('/1234/adunit', [300, 250], 'slot-div');
slot1.addService(googletag.companionAds()).addService(googletag.pubads());
...
googletag.companionAds().setRefreshUnfilledSlots(true);
...
googletag.enableServices();

For autoplay videos, the following additional change is recommended to prevent companion slots from being preloaded and then immediately replaced with companions.

googletag.pubads().disableInitialLoad();
...
googletag.enableServices();

Enum google.ima.ImaSdkSettings.VpaidMode

A set of constants for enabling VPAID functionality.

If the value is DISABLED VPAID ads will not play and an error will be returned if VPAID is requested. This is the default.

If the value is ENABLED VPAID is enabled using a cross domain iframe. The VPAID ad cannot access the site. VPAID ads that depend on friendly iframe access may not play.

If the value is INSECURE then VPAID ads are enabled. The VPAID ad will load in a friendly iframe. This allows the ad access to the site via javascript.

Enum google.ima.UiElements

Fields

COUNTDOWN

Enum specifying different UI elements that can be configured to be displayed or hidden. These settings may be ignored for AdSense and ADX ads.

Values

Value	Description
`COUNTDOWN`	Ad attribution is required for a countdown timer to be displayed. Both `UiElements.COUNTDOWN` and `UiElements.AD_ATTRIBUTION` must be present in `AdsRenderingSettings.uiElements`.

Enum google.ima.ViewMode

Fields

FULLSCREEN, NORMAL

Enum specifying different VPAID view modes for ads.

Values

Value	Description
`FULLSCREEN`	Fullscreen ad view mode. Indicates to the ads manager that the publisher considers the current AdDisplayContainer arrangement as fullscreen (i.e. simulated fullscreen). This does not cause the ads manager to enter fullscreen.
`NORMAL`	Normal ad view mode.

Constant google.ima.VERSION

A string containing the full version of the SDK.