As of July 5, 2017 the Flash SDK is deprecated. We recommend using the HTML5 SDK for inline ads with web video content.

Flash SDK Version 3 API Reference

  1. com.google.ads.ima.api
    1. Ad
    2. AdError
    3. AdErrorCodes
    4. AdErrorEvent
    5. AdErrorTypes
    6. AdEvent
    7. AdPodInfo
    8. AdsLoader
    9. AdsManager
    10. AdsManagerLoadedEvent
    11. AdsRenderingSettings
    12. AdsRequest
    13. AudioMimeTypes
    14. CompanionAd
    15. CompanionAdEnvironments
    16. CompanionAdSelectionSettings
    17. CompanionBackfillModes
    18. CustomContentLoadedEvent
    19. FlashCompanionAd
    20. HtmlCompanionAd
    21. ImaSdkSettings
    22. UiElements
    23. VideoDeliveryTypes
    24. VideoMimeTypes
    25. ViewModes

Implementing Classes

Fields

Methods

Interface that represents basic information that all ads share.

Properties

Name Type Description
adPodInfo AdPodInfo

Returns the AdPodInfo object associated with this Ad.

adSkippableState Boolean

Returns true if the ad can currently be skipped. For ads where skippable is false, this always returns false. When this value changes, the AdsManager fires an AdEvent.SKIPPABLE_STATE_CHANGED event.

adSystem String

Returns the source ad server information included in the ad response, or null if the information is not available.

apiFramework String

Identifies the API needed to execute the ad. When a VPAID ad unit is selected from a VAST document, the value for the apiFramework attribute will be "VPAID" (all caps). Returns null if this information is unavailable.

contentType String

Ad content type for selected creative from the VAST response, or null if this information is unavailable.

currentTime Number

The media file's time elapsed in seconds. Returns -1 if the current time is not yet available or the video ad hasn't started. Returns -2 if the elapsed time is unknown.

description String

Ad description from the VAST response, or null if this information is unavailable.

duration Number

The length of the media file in seconds. Returns -1 if the duration is not yet available or -2 if it is unknown.

height Number

Returns the height occupied by the creative. This height doesn't represent ad position, so it doesn't include spacing used to align the ad within the ad slot.

id String

Returns the ad ID from the VAST response. For legacy DART responses, this can be used to synchronize master ad and companion ads.

isci String

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

linear Boolean

Returns true if the ad is currently in linear playback mode, and false if the ad is in 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. When this value changes, the AdsManager will fire an AdEvent.LINEAR_CHANGED event.

mediaUrl String

Returns the URL of the media file (could be FLV or or another format) chosen from the ad based on the media selection settings currently in use. Returns null if this information is unavailable.

minSuggestedDuration Number

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.

Note: SDK does not enforce ad playback based on minimum suggested duration.

remainingTime Number

The amount of time left in the ad without user interaction. Returns -1 if the current time is not yet available or the video ad hasn't started. Returns -2 if the remaining time is unknown.

skippable Boolean

Returns true if an ad will become skippable at some point during playback. This is not an indication of whether the ad can currently be skipped.

surveyUrl String

Returns the URL of request to the survey vendor.

title String

Ad title from the VAST response, or null if this information is unavailable.

traffickingParameters Dictionary

If ad has custom metadata associated at the time of ad trafficking, this method allows retrieval of all metadata values. Returns a Dictionary with keys and their values. The Dictionary will be empty if this information is not available.

traffickingParametersAsString String

Returns all trafficking parameters as an unparsed string, or null if the parameters are not available.

width Number

Returns the width occupied by the creative. This width doesn't represent ad position, so it doesn't include spacing used to align the ad within the ad slot.

wrapperAdIds Array

An array of IDs associated with the VAST wrappers for a given ad. The IDs returned begin with the outer-most (first-returned) wrapper and end with the wrapper that was retrieved immediately prior to receiving the InLine ad response. An empty array is returned if there are no wrapper responses.

wrapperAdSystems Array

An array of ad systems associated with the VAST wrappers for a given ad. The ad systems returned begin with the outermost (first-returned) wrapper and end with the wrapper that was retrieved immediately prior to receiving the InLine ad. An empty array is returned if there are no wrapper responses.

Instance Methods

Array getCompanionAds(environment:String, width:Number, height:Number, settings?:CompanionAdSelectionSettings)

Returns an array of companionAds. This should only be used if the publisher wants to render companion ads manually. Use Google Publisher Tags (GPT) if you want the displaying of companion ads in an HTML environment to be handled automatically. If the video player calls for getCompanionAds, it must wait until after receiving the AdEvent.LOADED event, and any companions provided must not display until after the AdEvent.IMPRESSION event is received. Delaying companion display until after the AdEvent.IMPRESSION event prevents display of any companion banners in the case where the master ad fails to register an impression.

Parameter Type Description
environment String

The environment where a companion ad is loaded.

width Number

Required width of the companion ad.

height Number

Required height of the companion ad.

settings? CompanionAdSelectionSettings

CompanionAdSelectionSettings instance with criteria for selecting appropriate ads.

Back to top

interface AdError

Fields

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. All AdErrors are considered fatal. If your AdError event handler is called, you should destroy the AdsManager and resume your content.

Properties

Name Type Description
adIds Array

If ads are associated with the error, the ad IDs are returned in an array. The IDs returned begin with the outer-most (first-returned) wrapper and end with the InLine ad ID.

adSystems Array

If ads are associated with the error, the ad systems are returned in an array. For example, if there are multiple VAST wrappers, and an inline ad has an error during load or play, the list includes the system of each wrapper. When there are multiple VAST wrappers, the order of ad systems in the list matches the order of the wrappers. The first wrapper would correspond to the ad system in position 0 on the list, the second wrapper would correspond to the ad system in position 1, and so on.

errorCode int

Provides the error code for the error.

errorMessage String

Provides a short message in English describing the error.

errorType String

Returns a string indicating where a failure occurred (during ad loading or playing). Type definitions can be found in AdErrorTypes.

innerError Error

If Flash error is available it is saved and can be retrieved using the accessor. The user can see more details about what went wrong by inspecting the error instance.

vastErrorCode int

Returns VAST error code if available, otherwise returns AdErrorCodes.UNDEFINED_ERROR.

Back to top

class AdErrorCodes

Fields

ADS_PLAYER_LOAD_FAILED, ADS_REQUEST_FAILED, API_ERROR, COMPANION_AD_LOADING_FAILED, COMPANION_COULD_NOT_BE_RENDERED, COMPANION_DIMENSIONS_ERROR, COMPANION_HAS_UNSUPPORTED_TYPE, EXPECTED_DIFFERENT_VAST_AD_SIZE, GENERAL_COMPANIONS_ERROR, GENERAL_LINEAR_ERROR, GENERAL_NONLINEAR_ERROR, GENERAL_VPAID_ERROR, GENERAL_WRAPPER_ERROR, IMA_SDK_ERROR_CODE, INVALID_ADX_EXTENSION, INVALID_ARGUMENTS, LINEAR_FILE_DISPLAY_ERROR, LINEAR_FILE_DURATION_ERROR, LINEAR_FILE_LOAD_TIMEOUT, LINEAR_FILE_NOT_FOUND, NONLINEAR_DIMENSIONS_ERROR, NO_ADS_FOUND, PLAYLIST_MALFORMED_RESPONSE, SKIP_NOT_ALLOWED, UNDEFINED_ERROR, UNEXPECTED_VAST_AD, VAST_INLINE_EXPECTED, VAST_INVALID_URL, VAST_LINEAR_ASSET_MISMATCH, VAST_LINEAR_CREATIVE_NOT_FOUND, VAST_LOAD_TIMEOUT, VAST_MALFORMED_RESPONSE, VAST_MEDIA_ERROR, VAST_NONLINEAR_ASSET_MISMATCH, VAST_NON_LINEAR_CREATIVE_NOT_FOUND, VAST_PARSING_ERROR, VAST_SCHEMA_VALIDATION_FAILED, VAST_TOO_MANY_REDIRECTS, WRONG_VAST_AD_DURATION_OR_SIZE, WRONG_VAST_AD_LINEARITY

This class defines possible error codes raised while loading or playing ads. The AdErrorCodes are numeric values and can be in one of the following ranges: Standard VAST 3 compliant ad error codes use blocks below 1000. SDK specific error codes: 1000-1099 for high level generic errors 1100-1199 for low level generic errors

Constants

Name Value Description
ADS_PLAYER_LOAD_FAILED 1104

Load of the ads player failed.

ADS_REQUEST_FAILED 1103

Ads request failed.

API_ERROR 1102

Generic invalid usage of the API.

COMPANION_AD_LOADING_FAILED 603

A companion ad failed to load or render. Unable to fetch CompanionAds/Companion resource.

COMPANION_COULD_NOT_BE_RENDERED 602

Unable to display Required Companion.

COMPANION_DIMENSIONS_ERROR 601

Unable to display Companion because creative dimensions do not fit within companion display area (i.e., no available space)

COMPANION_HAS_UNSUPPORTED_TYPE 604

Couldn’t find companion resource with supported type.

EXPECTED_DIFFERENT_VAST_AD_SIZE 203

Video player expecting different size.

GENERAL_COMPANIONS_ERROR 600

General CompanionAds error.

GENERAL_LINEAR_ERROR 400

General Linear error. Video player is unable to display the linear ad.

GENERAL_NONLINEAR_ERROR 500

General NonLinearAds error.

GENERAL_VPAID_ERROR 901

General VPAID error.

GENERAL_WRAPPER_ERROR 300

General Wrapper error.

IMA_SDK_ERROR_CODE 1000

General SDK error code to categorize all non-VAST standard errors.

INVALID_ADX_EXTENSION 1105

An invalid Ad Exchange extension was found.

INVALID_ARGUMENTS 1101

Invalid Arguments were provided to sdk methods.

LINEAR_FILE_DISPLAY_ERROR 405

Problem displaying MediaFile. Video player found a MediaFile with supported type but couldn’t display it. The MediaFile may include unsupported codecs, a different MIME type than MediaFile type, an unsupported delivery method, etc.

LINEAR_FILE_DURATION_ERROR 406

Linear MediaFile’s actual duration varied from duration specified in Linear/Duration by more than 10% or 3 seconds (this is a recommendation).

LINEAR_FILE_LOAD_TIMEOUT 402

Timeout of MediaFile URI. The default timeout for media loading is 15 seconds.

LINEAR_FILE_NOT_FOUND 401

File not found. Unable to find Linear/MediaFile from URI.

NONLINEAR_DIMENSIONS_ERROR 501

Unable to display NonLinear ad because creative dimensions do not align with creative display area (i.e. creative dimension too large).

NO_ADS_FOUND 1001

No ads returned from the ad server.

PLAYLIST_MALFORMED_RESPONSE 1004

The ads list response was not recognized as a valid AdsList playlist.

SKIP_NOT_ALLOWED 1106

The provided ad type cannot be skipped.

UNDEFINED_ERROR 900

Other, undefined error.

UNEXPECTED_VAST_AD 200

Trafficking error. Video player received an ad type that it was not expecting and/or cannot display.

VAST_INLINE_EXPECTED 204

Video player expecting VAST inline ad.

VAST_INVALID_URL 303

No ads VAST response after one or more Wrappers. Also can be caused by empty VAST responses.

VAST_LINEAR_ASSET_MISMATCH 403

No assets were found in the VAST ad response that matched the capabilities of the video player. Couldn’t find MediaFile that is supported by this video player, based on the attributes of the MediaFile element.

VAST_LINEAR_CREATIVE_NOT_FOUND 1002

Failure to find linear creatives in VAST ad response.

VAST_LOAD_TIMEOUT 301

Timeout of VAST URI provided in Wrapper element, or of VAST URI provided in a subsequent Wrapper element. Includes request errors such as invalid URI, unreachable or request timeout for URI, and security or other exceptions related to requesting a VAST URI. Can also be caused by exceeding ad pod refresh limit.

VAST_MALFORMED_RESPONSE 100

XML parsing error.

VAST_MEDIA_ERROR 502

Unable to fetch NonLinearAds/NonLinear resource.

VAST_NONLINEAR_ASSET_MISMATCH 503

Couldn’t find NonLinear resource with supported type.

VAST_NON_LINEAR_CREATIVE_NOT_FOUND 1003

Failure to find non-linear creatives in VAST ad response.

VAST_PARSING_ERROR 102

VAST version of response not supported.

VAST_SCHEMA_VALIDATION_FAILED 101

VAST schema validation error.

VAST_TOO_MANY_REDIRECTS 302

The maximum number of VAST wrapper redirects has been reached. Wrapper limit reached, as defined by the video player. Too many Wrapper responses have been received with no InLine response.

WRONG_VAST_AD_DURATION_OR_SIZE 202

Video player expecting different duration or size.

WRONG_VAST_AD_LINEARITY 201

Video player expecting different linearity.

Back to top

class AdErrorEvent

Fields

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

Constants

Name Value Description
AD_ERROR adError

The AdErrorEvent.AD_ERROR constant defines the value of the type property of the event object for an error event.

The properties of the event object have the following values:

Property Value
bubbles false
cancelable false; there is no default behavior to cancel.
adError An instance of AdError that carries details about an error that occurred.

Properties

Name Type Description
error AdError

AdError that occurred when loading or playing an ad.

userRequestContext Object

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

Back to top

class AdErrorTypes

Fields

This class defines possible error types for ad loading and playing.

Constants

Name Value Description
AD_LOAD_ERROR adLoadError

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_ERROR adPlayError

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 AdEvent

Fields

The ad raises these event types as a notification when the ad state changes and when users interact with the ad, such as when the ad starts playing or when a user clicks on the ad. See the AdsManager class for a description of when each of these events will be dispatched. You can then register listeners for these various state changed events on the AdsManager. All events have the following properties unless otherwise noted:

Property Value
bubbles false
cancelable false; there is no default behavior to cancel.
ad An instance of Ad which exposes ad id and other ad data.

Constants

Name Value Description
AD_BREAK_READY adBreakReady

The AdEvent.AD_BREAK_READY constant defines the value of the type property of the event object for a adBreakReady event. Dispatched when an ad break would have been played if autoPlayAdBreaks is set to false.

AD_METADATA adMetadata

The AdEvent.AD_METADATA constant defines the value of the type property of the event object for a adMetadata event. Dispatched when an ad's read-only metadata has been parsed.

ALL_ADS_COMPLETED allAdsCompleted

The AdEvent.ALL_ADS_COMPLETED constant defines the value of the type property of the event object for a allAdsCompleted event. Dispatched when no more ads remain to be played.

CLICKED clicked

The AdEvent.CLICKED constant defines the value of the type property of the event object for a clicked event. Dispatched when a user has clicked on an ad and is presented with the destination page.

COMPLETED completed

The AdEvent.COMPLETED constant defines the value of the type property of the event object for a completed event. Dispatched when an ad has completed playing.

CONTENT_PAUSE_REQUESTED contentPauseRequested

The AdEvent.CONTENT_PAUSE_REQUESTED constant defines the value of the type property of the event object for a contentPauseRequested event. Dispatched when one or more linear ads are about to be played and the video content must be paused.

CONTENT_RESUME_REQUESTED contentResumeRequested

The AdEvent.CONTENT_RESUME_REQUESTED constant defines the value of the type property of the event object for a contentResumeRequested event. Dispatched when all linear ads have finished and the video content can be resumed.

DURATION_CHANGED durationChanged

The AdEvent.DURATION_CHANGED constant defines the value of the type property of the event object for a durationChanged event. Dispatched when the ad's duration property changes.

EXIT_FULLSCREEN exitFullscreen

The AdEvent.EXIT_FULLSCREEN constant defines the value of the type property of the event object for an exitFullscreen event. Dispatched when an ad has exited the full screen mode.

EXPANDED_CHANGED expandedChanged

The AdEvent.EXPANDED_CHANGED constant defines the value of the type property of the event object for an expandedChanged event. Dispatched when a VPAID ad's expanded property changes.

FIRST_QUARTILE firstQuartile

The AdEvent.FIRST_QUARTILE constant defines the value of the type property of the event object for a firstQuartile event. Dispatched when a linear ad has reached the first quartile while playing.

FULLSCREEN fullScreen

The AdEvent.FULLSCREEN constant defines the value of the type property of the event object for a fullScreen event. Dispatched when an ad has entered the full screen mode.

IMPRESSION impression

The AdEvent.IMPRESSION constant defines the value of the type property of the event object for an impression event. Dispatched when the impression URL is pinged.

INTERACTION interaction

The AdEvent.INTERACTION constant defines the value of the type property of the event object for an interaction event. Dispatched when a user interacts with a VPAID 2.0 ad.

LINEAR_CHANGED linearChanged

The AdEvent.LINEAR_CHANGED constant defines the value of the type property of the event object for a linearChanged event. Dispatched when an ad's linear property changes.

LOADED loaded

The AdEvent.LOADED constant defines the value of the type property of the event object for a loaded event. Dispatched when an ad has finished loading after init() has been called.

LOG log

The AdEvent.LOG constant defines the value of the type property of the event object for a log event. Dispatched when a VPAID ad fires a LOG event.

MIDPOINT midpoint

The AdEvent.MIDPOINT constant defines the value of the type property of the event object for a midpoint event. Dispatched when a linear ad has reached its midpoint.

PAUSED paused

The AdEvent.PAUSED constant defines the value of the type property of the event object for a paused event. Dispatched when ad has been paused.

RESUMED resumed

The AdEvent.RESUMED constant defines the value of the type property of the event object for a resumed event. Dispatched when a paused ad resumes.

SIZE_CHANGED sizeChanged

The AdEvent.SIZE_CHANGED constant defines the value of the type property of the event object for a sizeChanged event. Dispatched when the ad size has changed.

SKIPPABLE_STATE_CHANGED skippableStateChanged

The AdEvent.SKIPPABLE_STATE_CHANGED constant defines the value of the type property of the event object for a skippableStateChanged event. Dispatched when an ad's adSkippableState has changed.

SKIPPED skipped

The AdEvent.SKIPPED constant defines the value of the type property of the event object for a skipped event. Dispatched when an ad has been skipped.

STARTED started

The AdEvent.STARTED constant defines the value of the type property of the event object for an started event. Dispatched when an ad has started playing.

STOPPED stopped

The AdEvent.STOPPED constant defines the value of the type property of the event object for a stopped event. Dispatched when ad has been stopped. When an ad has been stopped, it cannot be resumed.

THIRD_QUARTILE thirdQuartile

The AdEvent.THIRD_QUARTILE constant defines the value of the type property of the event object for a thirdQuartile event. Dispatched when a linear ad has reached the third quartile.

USER_ACCEPTED_INVITATION userAcceptedInvitation

The AdEvent.USER_ACCEPTED_INVITATION constant defines the value of the type property of the event object for a userAcceptedInvitation event. Dispatched when a user accepted a VPAID ad's invitation.

USER_CLOSED userClosed

The AdEvent.USER_CLOSED constant defines the value of the type property of the event object for a userClosed event. Dispatched when a user closes the ad.

USER_MINIMIZED userMinimized

The AdEvent.USER_MINIMIZED constant defines the value of the type property of the event object for a userMinimized event. Dispatched when a user minimized the ad.

VOLUME_CHANGED volumeChanged

The AdEvent.VOLUME_CHANGED constant defines the value of the type property of the event object for a volumeChanged event. Dispatched when an ad's volume has changed.

VOLUME_MUTED volumeMuted

The AdEvent.VOLUME_MUTED constant defines the value of the type property of the event object for a volumeMuted event. Dispatched when the ad volume is muted.

Properties

Name Type Description
ad Ad

Returns the Ad object to allow publishers to identify which ad is being displayed. Ad is an optional parameter and it might not be available all the time. Returns null when unavailable.

adData Object

Allows extra data to be passed from the ad. VPAID ads may make use of this field. Original VPAID ad data can be accessed through the adData.originalData accessor.

Back to top

class AdPodInfo

Fields

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 each ad's position within the pod. The totalAds 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.

Constants

Name Value Description
UNKNOWN_DURATION -1

Used when the duration of the pod is unknown.

Properties

Name Type Description
adPosition Number

The position of this ad within the pod. The value returned is one-based (i.e., 1 of 2, 2 of 2, etc.).

isBumper Boolean

Returns true if this 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.

maxDuration Number

Returns the estimated maximum duration of this set of ads in seconds. A value of -1 means the maximum duration is unknown.

podIndex Number

Returns the index of the ad pod. For a preroll pod, returns 0. For midrolls 1, 2, ..., N is returned. For a postroll pod, -1 is returned. Defaults to 0 if this ad is not part of a pod, or this pod is not part of a playlist.

timeOffset Number

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

totalAds Number

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. Until the ad tag is loaded, the SDK assumes that each ad tag has 1 ad. Therefore, some AdEvents fired at the beginning of an ad break (AD_METADATA, LOADED, etc.) may only have 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.

Back to top

class AdsLoader

Fields

Constructors

Methods

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

Constants

Name Value Description
GOOGLEAPIS_HOST imasdk.googleapis.com
LEGACY_HOST s0.2mdn.net

Properties

Name Type Description
settings ImaSdkSettings

See com.google.ads.ima.api.ImaSdkSettings

Constructors

AdsLoader()

Create a new AdsLoader object.

Instance Methods

void addEventListener(type:String, listener:Function, useCapture?:Boolean, priority?:int, useWeakReference?:Boolean)

See flash.events.EventDispatcher

Parameter Type Description
type String
listener Function
useCapture? Boolean
priority? int
useWeakReference? Boolean

void contentComplete(contentId?:String)

Allows publishers to tell the SDK when any content completes, even content without ads. This allows the SDK to play post-roll ads, if any.

Parameter Type Description
contentId? String

Optional ID for content. This is not the same as contentId property on the request object. It could be as simple as an incremental numeric value.

void destroy()

Unload informs the SDK to release all resources currently held so that the memory can be freed by the garbage collector.

Boolean isLocallyDispatchedEvent(type:String)

Indicates event types that are dispatched by an instance of this class, in addition to the wrapped class. Any registered event listeners for such events will automatically be added to this instance, as well as to the wrapped remote instance.

Parameter Type Description
type String

event type.

void loadSdk()

This method loads the SDK, which will be used for requesting ads. Without calling this method, the SDK will be loaded automatically when ads are requested. Calling this method before requesting ads can reduce the latency between requesting and playing ads.

void requestAds(adsRequest:AdsRequest, userRequestContext?:Object)

This method takes an AdsRequest object with properties populated with parameters to make an ad request to an ad server. All AdsRequest objects must have at least the adTagUrl property set.

Parameter Type Description
adsRequest AdsRequest

Instance with properties set for ad request.

userRequestContext? Object

User-provided object that is associated with the ads request. It can be retrieved when the ads are loaded.

void requestLiveAds(adsRequest:AdsRequest, userRequestContext?:Object)

Request ads for live stream content, in which the SDK requests subsequent ads 0-2 minutes from initial ad break completion. The initial request is not randomized. Once the ad break completes, the same AdsRequest object is used to request future ad breaks. This method takes an AdsRequest object with properties populated with parameters to make an ad request to an ad server. All AdsRequest objects must have at least the adTagUrl property set. Ensure the AdsRequest object is set to provide enough ads to be played for the ad break.

Parameter Type Description
adsRequest AdsRequest

Instance with properties set for ad request.

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 AdsManager

Fields

Methods

Main control point for all VAST and legacy ads and ad formats. Wraps both single ad request and Ad Rules requests.

Properties

Name Type Description
adsContainer DisplayObjectContainer

Returns the ads container object in which the ads will be displayed. Add this object to the display prior to calling start().

cuePoints Array

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.

expanded Boolean

Returns true if the ad is expandable and is in the expanded state. False otherwise.

linear Boolean

Indicates the current linear vs. non-linear mode of operation for the current ad. When true, the ads manager is in a linear playback mode. Otherwise, the ads manager is in non-linear playback mode.

remainingTime Number

Gets the remaining time in seconds left in the current ad.

uiElements Array

Returns an array representing which UI elements are rendered by the IMA SDK for this ad. All values in the array are String values from UiElements, or empty. Some elements may be required to be displayed, or unable to be displayed for a given ad. In these cases, some modifications to the uiElements array may have no effect. Similarly, if some elements can not be displayed, trying to enable such element rendering through the use of uiElements will have no effect. As a result, you should always check uiElements after setting uiElements to a new value. uiElements will have correct values only after the AdEvent.LOADED has fired. For example, the SDK will render the countdown and ad program icon with the following code:

var newUiElements:Array = [UiElements.COUNTDOWN, UiElements.AD_ATTRIBUTION];
adsManager.uiElements = newUiElements;

Note: Only certain ad formats support built-in countdown and other UI elements. If a particular ad format does not have a default implementation available, it is up to the publisher to build their own.

volume Number

The current ad's volume. The value is between 0 and 1, and defaults to 0.5.

Instance Methods

void collapse()

Collapses the ad, if the ad supports it.

void destroy()

Ads might have assets loaded at runtime that need to be properly removed at the time of ad completion. It is recommended that you call destroy() once the ads manager has completed displaying all of the ads. Failure to call destroy() may lead to memory leaks.

void expand()

Expands the ad, if the ad supports it.

String handshakeVersion(playerVpaidVersion?:String)

If video player supports VPAID ads, then video player should pass in the supported version value before calling any of the other methods.

Parameter Type Description
playerVpaidVersion? String

void init(adSlotWidth:Number, adSlotHeight:Number, viewMode:String, desiredBitrate?:Number, creativeData?:String, environmentVars?:String)

Initialize the ad. This method must be called prior to start(). When initialization completes, the AdEvent.LOADED is fired.

Parameter Type Description
adSlotWidth Number

The ad slot width. For linear ads, this should be the width of the player.

adSlotHeight Number

The player height. For linear ads, this should be the height of the player.

viewMode String

The ViewMode of the player.

desiredBitrate? Number

Optional. The preferred kbps bitrate of the ad. Defaults to VPAID's 'unknown' value of -2.

creativeData? String

Optional. The string of data to pass to the creative.

environmentVars? String

Optional. The string of data that should be made known to the ad as it loads.

void pause()

Pauses the current ad.

void resize(adSlotWidth:Number, adSlotHeight:Number, viewMode:String)

Tells the SDK that the ad slot size has changed.

Parameter Type Description
adSlotWidth Number

The ad slot's new width.

adSlotHeight Number

The ad slot's new height.

viewMode String

The current view mode of the player.

void resume()

Resumes the current ad.

Boolean skip()

Skips the current ad when the adSkippableState is true. When called under other circumstances, skip has no effect.

void start()

Starts the current ad from the beginning. Can only be called once per ad.

void startLiveAds(maxPodDuration:Number)

Starts playing a sequence of ads when multiple ads are available in the VAST response during a live stream. The total duration of the ads should be less than or equal to maximum duration.

Parameter Type Description
maxPodDuration Number

maximum duration, in seconds, of all ads to be played. If the ad response duration exceeds this limit, remaining ads will not be played.

void stop()

Stops the current ad. Once stopped, the current ad cannot be resumed. In the case of Ad Rules or VMAP response, it will unload the entire ad break currently playing, but will continue to track the content playhead.

Back to top

class AdsManagerLoadedEvent

Fields

Methods

This event is raised when ads manager is successfully loaded from an ad server via an AdsLoader. You can register for this event on the AdsLoader object.

Constants

Name Value Description
ADS_MANAGER_LOADED adsManagerLoaded

The AdsManagerLoadedEvent.ADS_MANAGER_LOADED constant defines the value of the type property of the event object for a adsManagerLoaded event.

The properties of the event object have the following values:

Property Value
bubbles false
cancelable false; there is no default behavior to cancel.
adsManager An instance of AdsManager which exposes ads and supports displaying ads.

Properties

Name Type Description
userRequestContext 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: ability to relate ads response to a specific request and use user request content object as a key for identifying the response.

Instance Methods

AdsManager getAdsManager(contentPlayback?:Object, adsRenderingSettings?:AdsRenderingSettings, publisherVideoAdPlayback?:Object)

After ads are loaded from the ad servers, the publisher needs to play these ads with this AdsManager object. In order to obtain an AdsManager, it is strongly recommended to provide an object that returns the current position of the content playhead. Important: AdsManager instance could be null if there was an error creating it. Error would be dispatched as an event and not thrown while calling getAdsManager method. The AdsManager requires the publisher to subscribe to various events during ad playback, including the following before init() is called:

  1. AdErrorEvent.AD_ERROR
  2. AdEvent.ALL_ADS_COMPLETE
  3. AdEvent.CONTENT_PAUSE_REQUESTED
  4. AdEvent.CONTENT_RESUME_REQUESTED
Here is a small example:
     private function adsManagerLoadedHandler(
       adsManagerLoadedEvent:AdsManagerLoadedEvent):void {
       var contentPlayback:Object = {
         time:function():Number {
           return contentNetStream.time * 1000; // Make time in ms.
         }
       };
       var adsManager:AdsManager =
           adsManagerLoadedEvent.getAdsManager(contentPlayback);
       if (adsManager) {
         // ... remaining omitted.
       }
     }
     

Parameter Type Description
contentPlayback? Object

Object that tracks the playhead of the publisher's content. It must contain a time() function which allows the SDK to poll for the playhead's position in milliseconds. This allows the SDK to display mid-rolls if the ad server responds with an Ad Rules or VMAP response. Most cases should include this object for forward compatibility. Null can be passed if the content doesn't have an obvious playtime, such as a game. It can optionally include duration property.

adsRenderingSettings? AdsRenderingSettings

Ads rendering settings are used to change the way ads are rendered to the client. Among these options are the media selection settings that change the way media files are selected from the server response, as the response may contain multiple media files. Publishers can specify which MIME types, delivery modes, and bitrates they prefer. The AdsManager finds the closest matching media file to the publisher-specified settings. If no match is found, the AdsManager falls back to any valid media URL. If the publisher does not specify adsRenderingSettings, the default settings are used.

publisherVideoAdPlayback? Object

For internal use. Not officially supported.

Back to top

class AdsRenderingSettings

Fields

This object defines parameters that control the rendering of ads. The following paramaters help select media from a VAST ads response. They are not strict matches, only hints.

We match the following settings in order:

  1. mimeTypes
  2. delivery
  3. bitrate
For more information, refer to the IAB description of VAST.

Properties

Name Type Description
autoAlign Boolean

Set to false if you wish to have precise control over the positioning of all non-linear ads. Defaults to true. When this value is false, the ad is positioned in the top left corner (0,0) of the adsContainer.

bitrate int

Maximum recommended bitrate. The value is in kbit/s. SDK will select media which has a bitrate below the specified max or the closest bitrate if there is no media with a lower bitrate found. Default value, -1, means the bitrate will be selected by the SDK.

delivery String

Hint for the delivery types that the publisher wants to display. Valid values for this parameter are progressive and streaming. Default is progressive.

enablePreloading Boolean

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

linearAdPreferred Boolean

Specifies the creative selection preference to use when both linear and non-linear creatives are available.

mediaTimeout int

Timeout for loading the media file for an ad. This value is in seconds. If this timeout is exceeded, the ad playback is canceled and the next ad in the pod plays, if available. The default value is 0, which will correspond to the default SDK specific timeout.

mimeTypes Array

Specifies the MIME types of media files that the publisher wants to prioritize for media selection and display.

useStyledNonLinearAds Boolean

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

Back to top

class AdsRequest

Fields

This object defines a set of inputs that can be used to request ads. The primary required property is adTagUrl, which can specify a URL to a Google ad server or any third-party URL that returns a valid VAST response. The other required parameters include:

  • linearAdSlotWidth
  • linearAdSlotHeight
  • nonLinearAdSlotWidth
  • nonLinearAdSlotHeight
Use this object in conjunction with an AdsLoader to request ads from the specified server.

Properties

Name Type Description
adTagUrl String

Specifies full URL to use for ads loading from an ad server. Required for any AdsRequest. For details on constructing the ad tag url, see Create a master video tag manually.

adWillAutoPlay Boolean

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. Not calling this function leaves the setting as unknown.

Note: Changing this setting will have no impact on ad playback.

adsResponse String

Specifies a VAST 2.0+ or VMAP 1.0+ ads response to be used as the ads response instead of making a request to the adTagUrl. This can be useful for debugging and other situations where the VAST response is already available.

disableCompanionAds Boolean

Indicates whether companion ads included in the VAST response should not be displayed. By default, this is false.

language String

A language code used to request ads in that language. This may be any ISO 639-1 (two-letter) or ISO 639-2 (three-letter) code. This is an optional parameter for internationalized ads rendering. Defaults to the system language. Please refer here for a list of valid codes: http://www.loc.gov/standards/iso639-2/php/English_list.php.

linearAdSlotHeight Number

Required parameter that 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 the actual ad's height.

linearAdSlotWidth Number

Required parameter that 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 the actual ad's width.

nonLinearAdSlotHeight Number

Required parameter that 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, and is used prior to returning an AdsManager to the publisher. This value does not need to match actual ad's height.

nonLinearAdSlotWidth Number

Required parameter that 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, and is used prior to returning an AdsManager to the publisher. This value does not need to match actual ad's width.

Back to top

class AudioMimeTypes

Fields

This class defines constants for audio MIME types selection. This is used mainly for VAST media selection.

Constants

Name Value Description
MP4 audio/mp4

Allows selection of MP4 audio file as the ad creative.

Properties

Name Type Description
DEFAULT_MIMETYPES Array

Default MIME types used for selecting which media file to play in an ad.

Back to top

interface CompanionAd

Fields

Interface that represents basic information shared by all companion ads.

Properties

Name Type Description
environment String

Returns the environment where the companion ad would be loaded.

Back to top

class CompanionAdEnvironments

Fields

This class defines possible environments where a companion ad is loaded and/or served.

Constants

Name Value Description
FLASH flash

Flash companion ads can be loaded and rendered within the Flash environment. Ads can be images, simple SWFs etc.

HTML html

HTML ads can be loaded and rendered within an HTML environment. Ads can be HTML resources, IFrame resources or static resources like images or simple SWFs.

Back to top

class CompanionAdSelectionSettings

Fields

This class defines various criteria for selecting companion ads.

Constants

Name Value Description
COMPANION_SIZE_EXACT_FIT CompanionSize_ExactFit

Setting for returning companion ads that exactly fit the size criteria.

COMPANION_SIZE_IGNORE CompanionSize_Ignore

Setting for ignoring companion size criteria.

COMPANION_SIZE_NEAR_FIT CompanionSize_NearFit

Setting for returning companion ads that nearly fit the size criteria.

VAST_CREATIVE_TYPE_ALL VASTCreativeType_All

Setting for choosing all creative types.

VAST_CREATIVE_TYPE_FLASH VASTCreativeType_Flash

Setting for choosing Flash creative type.

VAST_CREATIVE_TYPE_IMAGE VASTCreativeType_Image

Setting for choosing Image creative type.

VAST_RESOURCE_TYPE_ALL VASTResourceType_All

Setting for choosing all resource types.

VAST_RESOURCE_TYPE_HTML VASTResourceType_HTML

Setting for choosing html resource type.

VAST_RESOURCE_TYPE_IFRAME VASTResourceType_IFrame

Setting for choosing iframe resource type.

VAST_RESOURCE_TYPE_STATIC VASTResourceType_Static

Setting for choosing static resource type.

Properties

Name Type Description
creativeType String

Creative or MIME type of the companion ad that should be returned. This is applicable for VAST ads.

nearFitPercent Number

Minimum percent of requested size that a companion ad must be to be considered a near fit. The range is 0-100. Companion ads within the nearFitPercent size range are considered a near fit. Default is 90%.

resourceType String

Resource type of the companion ad that should be returned. This is applicable for VAST ads.

sizeCriteria String

Size criteria for selecting companion ads.

Back to top

class CompanionBackfillModes

Fields

Defines a set of constants for the companion backfill setting. This setting indicates whether companions should be backfilled in various scenarios. The default value is CompanionBackfillModes.ALWAYS. Note that client-side companion backfill requries tagging your companions properly with 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, another change is recommended to prevent companion slots from being preloaded and then immediately replaced with companions.

   googletag.pubads().disableInitialLoad();
   ...
   googletag.enableServices();
   
Note that companion backfill can be filled with eligible display ads from the DFP network's directly sold inventory or Ad Exchange/AdSense backfill.

Constants

Name Value Description
ALWAYS always

Companion backfill will be attempted in all situations, even when there is no master ad returned.

ONLY_FOR_MASTER_AD onlyForMasterAd

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.

Back to top

class CustomContentLoadedEvent

Fields

Methods

Represents a legacy custom content ad with companions.

Properties

Name Type Description
CUSTOM_CONTENT_LOADED String

The type string representing the legacy custom content event.

content String

Custom ad provides its content, which can be in any format: XML, JSON, etc.

userRequestContext Object

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

Instance Methods

void displayCompanions()

Display companions using an underlying Google Publisher Tagging (GPT) rendering service. All the slots defined by GPT will be populated for the master ad. This method is only supported for custom ads trafficked from DoubleClick ad servers.

Object getCustomContentAd()

Back to top

interface FlashCompanionAd

Fields

Methods

Interface that represents information about a flash companion ad. The companion ad can be loaded and played on the publisher's display object container.

Properties

Name Type Description
adsContainer DisplayObjectContainer

Returns the container in which the ads will be displayed. Add this object to the display prior to calling start()

Instance Methods

void destroy()

It is recommended that you call destroy when the companion ad has been displayed and will not be used anymore.

void init()

Loads the flash companion ad.

void start()

Starts the flash companion ad in the display object container. If the ad resource is not already loaded, it will be loaded before playing.

Back to top

interface HtmlCompanionAd

Fields

An HTML companion ad is a static resource like image or swf or an html code that can be rendered in an html environment.

Properties

Name Type Description
content String

Returns companion ad's html content. The content is returned to the publisher and can be rendered in an iframe. Escapes the characters in the content using EcmaScript string rules. Alert: Do not modify the HTML snippet in any way. The terms of your agreement prohibit this and we can't make exceptions because, when altered, the code for companion ad rendering could break.

Back to top

interface ImaSdkSettings

Fields

Defines global SDK settings that affect ads requests, companion rendering, etc.

Properties

Name Type Description
autoPlayAdBreaks Boolean

The default value is true. This setting ensures ads are played automatically in VMAP and ad rules. Changing it to false allows publishers to control ad playback. When this setting is false, instead of automatically playing the adBreak, an AD_BREAK_READY event will be fired when the adBreak would have been played.

companionBackfill String

The default value is CompanionBackfillModes.ALWAYS. For DFP requests, if the response causes an error or does not contain enough companion ads to fill all the GPT ad slots, additional requests will be made to fill those slots if this is set to CompanionBackfillModes.ALWAYS.

numRedirects uint

The default is 4. 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. In the future, it may be applied to other types of redirected ads.

playerType String

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:

     
     adsLoader.settings.playerType = "google/gmf-player";
     

playerVersion String

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:

     
     adsLoader.settings.playerVersion = "1.0.0";
     

ppid String

Sets the publisher provided ID (ppid). A publisher provided ID can be used to anonymously identify users in cookieless environments and, if set to nothing other than null or the empty string, is sent with all ad requests and impression pings to the DFP server.

uniqueAds Boolean

AdSense and Ad Exchange only. The default value is true. If enabled, ensures that unique ads are returned across several ad requests for the same content ID. This has no effect on non-AdSense and non-AdExchange ads.

Back to top

class UiElements

Fields

Defines UI elements.

Constants

Name Value Description
AD_ATTRIBUTION adAttribution
CLICK_BUTTON clickButton
CLOSE_BUTTON closeButton

Indicates that the ad has a built-in close button.

COMPLIANCE_ICONS complianceIcons

Several initiatives in the advertising industry involve using icons that overlays on top of an ad to provide some extended functionality such as to communicate with consumers or otherwise fulfill requirements of a specific initiative. The video player can use this value to avoid displaying duplicate icons over any icons that might be provided in the ad. Until the industry provides more guidance on how to pass metadata using common ad-serving protocols, this property is limited to a single value. If one or more compliance icons are present within the ad, AdsManager.uiElements will include COMPLIANCE_ICONS. If it's present, the video player should not display any compliance icons of its own.

COUNTDOWN countdown

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

SKIP_BUTTON skipButton

Back to top

class VideoDeliveryTypes

Fields

This class defines constants for video delivery to the video player.

Constants

Name Value Description
PROGRESSIVE progressive

Videos are downloaded using HTTP.

STREAMING streaming

Videos are streamed from a streaming server.

Properties

Name Type Description
DEFAULT String

Default mode that will be used for selecting which media file to play in a video ad.

Back to top

class VideoMimeTypes

Fields

This class defines constants for video MIME types selection. This is used mainly for VAST media selection.

Constants

Name Value Description
FLV video/x-flv

If URL to a FLV (Flash Video) video is included in VAST response, this constant allows selection of FLV video file as the ad video.

MP4 video/x-mp4

Since Flash Player 9 Update 3 Flash Video also supports the MPEG-4 international standard, if URL to a MPEG-4 video is included in VAST response, this constant allows selection of MPEG-4 video file as the ad video.

Properties

Name Type Description
DEFAULT_MIMETYPES Array

Default MIME types used for selecting which media file to play in a video ad.

Back to top

class ViewModes

Fields

viewMode indicates the current viewing mode for ads as defined by the publisher. viewMode is applicable for AdSense and VPAID ads only.

Constants

Name Value Description
FULLSCREEN fullscreen

Fullscreen VPAID ad view mode. Note about AdSense overlay ads: Setting ViewModes.FULLSCREEN causes ads to behave as linear ads, taking up the entire allowed area.

NORMAL normal

Normal VPAID ad view mode. Note about AdSense overlay ads: Setting ViewModes.NORMAL causes ads with a height of 90 pixels or less to behave as non-linear ads, occupying only the area necessary for the ad to render. Ads with a height exceeding 90 pixels behave as linear ads, which occupy the entire allowed area.

THUMBNAIL thumbnail

Thumbnail VPAID ad view mode.

Back to top

Send feedback about...

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