Google IMA HTML5 SDK APIs

    1. google.ima.Ad
    2. google.ima.AdDisplayContainer
    3. google.ima.AdError
    4. google.ima.AdError.ErrorCode
    5. google.ima.AdError.Type
    6. google.ima.AdErrorEvent
    7. google.ima.AdErrorEvent.Type
    8. google.ima.AdEvent
    9. google.ima.AdEvent.Type
    10. google.ima.AdPodInfo
    11. google.ima.AdsLoader
    12. google.ima.AdsManager
    13. google.ima.AdsManagerLoadedEvent
    14. google.ima.AdsManagerLoadedEvent.Type
    15. google.ima.AdsRenderingSettings
    16. google.ima.AdsRequest
    17. google.ima.CompanionAd
    18. google.ima.CompanionAdSelectionSettings
    19. google.ima.CompanionAdSelectionSettings.CreativeType
    20. google.ima.CompanionAdSelectionSettings.ResourceType
    21. google.ima.CompanionAdSelectionSettings.SizeCriteria
    22. google.ima.ImaSdkSettings
    23. google.ima.ImaSdkSettings.CompanionBackfillMode
    24. google.ima.ImaSdkSettings.VpaidMode
    25. google.ima.UiElements
    26. google.ima.ViewMode
    27. google.ima.VERSION

Interface google.ima.Ad

Methods

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.

getAdvertiserName()

The advertiser name as defined by the serving party.

Returns string: The advertiser name, or the empty string if this information is unavailable.

getApiFramework()

Identifies the API needed to execute the ad. This corresponds with the apiFramework specified in vast.

Returns string: The API framework need to execute the ad, or null 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.

getCreativeAdId()

Returns the ISCI (Industry Standard Commercial Identifier) code for an ad, or empty string if the code is unavailable. This is the Ad-ID of the creative in the VAST response.

Returns string:

getCreativeId()

Retrieves the ID of the selected creative for the ad.

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

getDealId()

Returns the first deal ID present in the wrapper chain for the current ad, starting from the top. Returns the empty string if unavailable.

Returns string:

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.

getMediaUrl()

Returns the URL of the media file chosen from the ad based on the media selection settings currently in use. Returns null if this information is unavailable. Available on STARTED event.

Returns string:

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.

getSkipTimeOffset()

The number of seconds of playback before the ad becomes skippable. -1 is returned for non skippable ads or if this is unavailable.

Returns number: The offset in seconds, or -1.

getSurveyUrl()

Returns the URL associated with the survey for the given ad. Returns null if unavailable.

Returns string:

getTitle()

Returns the title of this ad from the VAST response.

Returns string: The title, empty if not specified.

getTraffickingParameters()

Gets custom parameters associated with the ad at the time of ad trafficking.

Returns Object.: A mapping of trafficking keys to their values, or the empty Object if this information is not available.

getTraffickingParametersString()

Gets custom parameters associated with the ad at the time of ad trafficking. Returns a raw string version of the parsed parameters from getTraffickingParameters.

Returns string: Trafficking parameters, or the empty string if this information is not available.

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.

getUniversalAdIdRegistry()

The registry associated with cataloging the UniversalAdId of the selected creative for the ad.

Returns string: Returns the registry value, or "unknown" if unavailable.

getUniversalAdIdValue()

The UniversalAdId of the selected creative for the ad.

Returns string: Returns the id value or "unknown" if unavailable.

getVastMediaHeight()

Returns the VAST media height of the selected creative.

Returns number: The VAST media height of the selected creative or 0 if none is selected.

getVastMediaWidth()

Returns the VAST media width of the selected creative.

Returns number: The VAST media width of the selected creative or 0 if none is selected.

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.

getWrapperCreativeIds()

Selected creative 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' creatives, 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.

Back to top

Class google.ima.AdDisplayContainer

Methods

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.

Back to top

Class google.ima.AdError

Methods

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

Back to top

Enum google.ima.AdError.ErrorCode

Fields

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 5 seconds for initial VAST requests and 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 8 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_PROBLEM_DISPLAYING_MEDIA_FILE

Problem displaying MediaFile. Currently used if video playback is stopped due to poor playback quality.

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

The ad response contained an unsupported VAST version.

VAST_WRAPPER_ERROR

General VAST wrapper error.

VIDEO_PLAY_ERROR

There was an error playing the video ad.

Back to top

Enum google.ima.AdError.Type

Fields

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.

Back to top

Class google.ima.AdErrorEvent

Methods

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.

Back to top

Enum google.ima.AdErrorEvent.Type

Fields

Types of AdErrorEvents

Values

Value Description
AD_ERROR

Fired when an error occurred while the ad was loading or playing.

Back to top

Class google.ima.AdEvent

Methods

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.

Back to top

Enum google.ima.AdEvent.Type

Fields

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.

DURATION_CHANGE

Fired when the ad's duration changes.

FIRST_QUARTILE

Fired when the ad playhead crosses first quartile.

IMPRESSION

Fired when the impression URL has been pinged.

INTERACTION

Fired when an ad triggers the interaction callback. Ad interactions contain an interaction ID string in the ad data.

LINEAR_CHANGED

Fired when the displayed ad changes from linear to nonlinear, or vice versa.

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.

Back to top

Interface google.ima.AdPodInfo

Methods

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.

For pods in VOD streams with dynamically inserted ads, 0...N is returned regardless of whether the ad is a pre-, mid-, or post-roll.

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 pods in VOD streams with dynamically inserted ads, stream time is returned.

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

Back to top

Class google.ima.AdsLoader

Methods

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.

Back to top

Interface google.ima.AdsManager

Methods

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.

discardAdBreak()

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 the current ad. This is no-op for HTML5 SDK.

getAdSkippableState()

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

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, opt_videoElement)

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.

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

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

start()

Start playing the ads.

stop()

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

updateAdsRenderingSettings(adsRenderingSettings)

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.

Parameter Type Description
adsRenderingSettings google.ima.AdsRenderingSettings

The updated ads rendering settings.

Back to top

Class google.ima.AdsManagerLoadedEvent

Methods

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.

Back to top

Enum google.ima.AdsManagerLoadedEvent.Type

Fields

Types of AdsManagerLoadedEvents.

Values

Value Description
ADS_MANAGER_LOADED

Fired when the ads have been loaded and an AdsManager is available.

Back to top

Class google.ima.AdsRenderingSettings

Fields

Defines parameters that control the rendering of ads.

Properties

Name Type Description
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. The 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.

enablePreloading boolean

Enables preloading of video assets. For more info see our guide to preloading media.

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 8 seconds.

mimeTypes Array.<string>

Only supported for linear video mime types. 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.

playAdsAfterTime

For VMAP and ad rules playlists, only play ad breaks scheduled after this time (in seconds). This setting is strictly after - e.g. setting playAdsAfterTime to 15 will cause IMA to ignore an ad break scheduled to play at 15s.

restoreCustomPlaybackStateOnAdBreakComplete boolean

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. The elements in this array are ignored for AdSense/AdX ads.

useStyledLinearAds

Render linear ads with full UI styling. This setting does not apply to AdSense/AdX ads or ads played in a mobile context that already use full UI styling by default.

useStyledNonLinearAds boolean

Render non-linear ads with a close and recall button.

Back to top

Class google.ima.AdsRequest

Fields

Methods

A class for specifying properties of the ad request.

Properties

Name Type Description
adsResponse

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

Specifies the ad tag url that is requested from the ad server. For details on constructing the ad tag url, see Create a master video tag manually.

This parameter is required.

contentDuration

Specifies the duration of the content in seconds to be shown. Used in AdX requests.

This parameter is optional.

contentKeywords

Specifies the keywords used to describe the content to be shown. Used in AdX requests.

This parameter is optional.

contentTitle

Specifies the title of the content to be shown. Used in AdX requests.

This parameter is optional.

forceNonLinearFullSlot

Forces non-linear AdSense ads to render as linear fullslot. If set, the content video will be paused and the non-linear text or image ad will be rendered as fullslot. The content video will resume once the ad has been skipped or closed.

linearAdSlotHeight

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

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.

liveStreamPrefetchSeconds

Specifies the maximum amount of time to wait, after calling requestAds, before requesting the ad tag URL. This can be used to stagger requests during a live-stream event, in order to mitigate spikes in the number of requests.

nonLinearAdSlotHeight

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

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.

vastLoadTimeout

Override for default VAST load timeout in milliseconds for a single wrapper. The default timeout is 5 seconds.

This parameter is optional.

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.

Back to top

Interface google.ima.CompanionAd

Methods

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.

Back to top

Class google.ima.CompanionAdSelectionSettings

Fields

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.

Back to top

Enum google.ima.CompanionAdSelectionSettings.CreativeType

Fields

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

Back to top

Enum google.ima.CompanionAdSelectionSettings.ResourceType

Fields

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

Back to top

Enum google.ima.CompanionAdSelectionSettings.SizeCriteria

Fields

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.

Back to top

Class google.ima.ImaSdkSettings

Methods

This class contains SDK-wide settings.

getCompanionBackfill()

Returns the current companion backfill mode.

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

getDisableCustomPlaybackForIOS10Plus()

Gets whether to disable custom playback on iOS 10+ browsers. The default value is false.

Returns boolean:

getDisableFlashAds()


Returns boolean: Whether flash ads should be disabled.

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.

setDisableCustomPlaybackForIOS10Plus(disable)

Sets whether to disable custom playback on iOS 10+ browsers. If true, ads will play inline if the content video is inline. This enables TrueView skippable ads. However, the ad will stay inline and not support iOS's native fullscreen. When false, ads will play in the same player as your content. The value set here when an AdDisplayContainer is created is used for the lifetime of the container. The default value is false.

Parameter Type Description
disable boolean

Whether or not to disable custom playback.

setDisableFlashAds(disableFlashAds)

Sets whether flash ads should be disabled.

Parameter Type Description
disableFlashAds boolean

Whether flash ads should be disabled.

setLocale(locale)

Sets the publisher provided locale. Must be called before creating AdsLoader or AdDisplayContainer. The locale specifies the language in which to display UI elements and can be any two-letter ISO 639-1 code.

Parameter Type Description
locale string

Publisher-provided locale.

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.

Back to top

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

Back to top

Enum google.ima.ImaSdkSettings.VpaidMode

A set of constants for enabling VPAID functionality.

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. This is the default.

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

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.

Back to top

Enum google.ima.UiElements

Fields

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.

Back to top

Enum google.ima.ViewMode

Fields

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.

Back to top

Constant google.ima.VERSION

A string containing the full version of the SDK.

Send feedback about...

IMA SDK for HTML5
Need help? Visit our support page.