Base classes for IAB VAST handling.
npm install iab-vast-model    
Base classes for IAB VAST handling. Supports the full IAB VAST 2.0, 3.0, and 4.0
specifications.
To parse a tag into model objects, use
iab-vast-parser.
To load and parse a chain of VAST files, use
iab-vast-loader.
``javascript
import { VAST } from 'iab-vast-model'
const vast = new VAST()
// ... Do your thing ...
`
The API attempts to favor developer experience over mapping the VAST
specifications to classes one-to-one. That has a few implications:
- You won't find classes corresponding to , ,
, and . Instead, those have
been folded into their parent objects.
- Where a child object can occur multiple times, the corresponding property will
either be an array or a SortedList. The latter models VAST's sequence
attribute and automatically orders elements by its value.
- Elements that are not required are null by default. A typical example isTrackingEvents
on the ads in a Creative.
#### Table of Contents
- AbsoluteTimeOffset
- AbstractAd
- adSystem
- conditionalAd
- creatives
- errors
- extensions
- id
- impressions
- pricing
- verifications
- viewableImpression
- AbstractClicks
- clickThrough
- clickTrackings
- AbstractExtension
- type
- xmlElement
- AbstractResource
- uri
- AbstractTimeOffset
- value
- AbstractVerificationResource
- apiFramework
- AdBuffet
- adPod
- ads
- SortedList
- add
- clear
- get
- length
- remove
- toArray
- TrackingEvents
- add
- get
- types
- Creative
- adID
- apiFramework
- companionAds
- extensions
- id
- linear
- nonLinearAds
- universalAdId
- Companion
- adParameters
- adSlotID
- altText
- apiFramework
- assetHeight
- assetWidth
- clickThrough
- clickTrackings
- expandedHeight
- expandedWidth
- height
- id
- pxratio
- resource
- trackingEvents
- width
- NonLinear
- adParameters
- apiFramework
- clickThrough
- clickTrackings
- expandedHeight
- expandedWidth
- height
- id
- maintainAspectRatio
- minSuggestedDuration
- resource
- scalable
- width
- Linear
- adParameters
- duration
- icons
- interactiveCreativeFiles
- mediaFiles
- mezzanine
- skipoffset
- trackingEvents
- videoClicks
- AdPod
- ads
- AdSystem
- name
- version
- InLine
- adTitle
- advertiser
- categories
- description
- surveys
- Wrapper
- allowMultipleAds
- fallbackOnNoAd
- followAdditionalWrappers
- vastAdTagURI
- Icon
- apiFramework
- clicks
- duration
- height
- offset
- program
- pxratio
- resource
- viewTrackings
- width
- xPosition
- yPosition
- MediaFile
- apiFramework
- bitrate
- codec
- delivery
- height
- id
- maintainAspectRatio
- maxBitrate
- minBitrate
- scalable
- type
- uri
- width
- InteractiveCreativeFile
- apiFramework
- type
- uri
- Category
- authority
- code
- Click
- id
- uri
- CompanionAds
- companions
- required
- CreativeExtension
- UniversalAdId
- creativeIdentifier
- idRegistry
- idValue
- StaticResource
- creativeType
- Pricing
- currency
- model
- value
- VideoClicks
- customClicks
- VAST
- errors
- uri
- version
- Extension
- FlashResource
- Verification
- flashResources
- javaScriptResources
- vendor
- viewableImpression
- HTMLResource
- IconClicks
- ViewableImpression
- id
- notViewables
- viewables
- viewUndetermineds
- Impression
- id
- uri
- IFrameResource
- JavaScriptResource
- NonLinearAds
- nonLinears
- trackingEvents
- TrackingEvent
- offset
- uri
- RelativeTimeOffset
- SortedListItem
- sequence
- Survey
- type
- uri
Extends AbstractTimeOffset
Represents a time offset expressed as an absolute duration in seconds.
Extends SortedListItem
Abstract class for ads (i.e., InLine and Wrapper).
#### adSystem
The ad system for this ad.
Type: AdSystem
#### conditionalAd
The conditional attribute for this ad.
Type: boolean
#### creatives
The creatives for this ad.
Type: SortedList<Creative>
#### errors
The error-tracking URIs for this ad.
#### extensions
The extensions for this ad.
#### id
The ad server-defined identifier for this ad.
Type: string
#### impressions
The impression-tracking configurations for this ad.
Type: Array<Impression>
#### pricing
The pricing configuration for this ad.
Type: Pricing
#### verifications
The verifications for this ad.
Type: Array<Verification>
#### viewableImpression
The viewable impression for this ad.
Type: ViewableImpression
Stores the click-through URI and a set of click-tracking pixels.
#### clickThrough
The click-through configuration.
Type: Click
#### clickTrackings
The click-tracking configurations.
Base class for VAST Extension as well as CreativeExtension.
#### type
The MIME type of any code that might be included in the extension.
Type: string
#### xmlElement
The XML DOM element.
Type: Element
Base class for a verification resource used by a HTMLResource, a
IFrameResource and a StaticResource.
#### uri
The URI to this resource.
Type: string
Represents a time offset.
#### value
The value for this offset.
Type: number
Extends AbstractResource
Base class for a verification resource used by a FlashResource and a
JavaScriptResource.
#### apiFramework
The name of the API framework.
Type: string
Represents a VAST ad buffet.
#### adPod
The ad pod for this ad buffet.
Type: AdPod
#### ads
The ads in this ad buffet.
Type: SortedList
Represents a list of SortedListItems, ordered by
SortedListItem#sequence.
#### add
Adds the given item to this list.
Parameters
- item SortedListItem the item.
#### clear
Empties this list.
#### get
Gets the item at the given index.
Parameters
- index number the index.
Returns SortedListItem the item.
#### length
The length of this list.
Type: number
#### remove
Removes the given item from this list.
Parameters
- item SortedListItem the item.
#### toArray
Creates an array representation of this list.
Returns Array<SortedListItem> the item array.
Configures tracking events. Maps VAST event types to arrays of
TrackingEvent instances.
#### add
Adds a tracking-event configuration for the given event type.
Parameters
- event string the event type.config
- TrackingEvent the tracking event configuration.
#### get
Gets the tracking-event configurations for the given event type.
Parameters
- event string the event type.
Returns Array<TrackingEvent> the tracking event configurations.
#### types
The event types tracked by this configuration.
Extends SortedListItem
Represents a creative.
#### adID
The ID of the Ad with which this creative is served.
Required for VAST 2.0 and 3.0, optional for VAST 4.0.
Type: string
#### apiFramework
The string that identifies an API that is needed to execute this creative.
Type: string
#### companionAds
The companion ads for this creative, if any.
Type: CompanionAds
#### extensions
The creative extensions for this creative.
Type: Array<CreativeExtension>
#### id
The ID of this creative.
Type: string
#### linear
The linear ad for this creative, if any.
Type: Linear
#### nonLinearAds
The non-linear ads for this creative, if any.
Type: NonLinearAds
#### universalAdId
The unique creative identifier for this creative.
Type: UniversalAdId
Represents a single companion inside CompanionAds.
#### adParameters
The ad parameters for this companion ad.
Type: string
#### adSlotID
The ad slot ID of this companion ad.
Type: string
#### altText
The alt text of this companion ad.
Type: string
#### apiFramework
The API framework used by this companion ad.
Type: string
#### assetHeight
The height of this companion ad's asset in pixels.
Type: number
#### assetWidth
The width of this companion ad's asset in pixels.
Type: number
#### clickThrough
The click-through configuration.
Type: Click
#### clickTrackings
The click-tracking configurations.
#### expandedHeight
The expanded height of this companion ad in pixels.
Type: number
#### expandedWidth
The expanded width of this companion ad in pixels.
Type: number
#### height
The height of this companion ad in pixels.
Type: number
#### id
The ID for this companion ad.
Type: string
#### pxratio
The pixel ratio for which the companion creative is intended.
Type: string
#### resource
The resource associated with this companion ad.
Type: (StaticResource \| IFrameResource \| HTMLResource)
#### trackingEvents
The event-tracking configuration for this companion ad.
Type: TrackingEvents
#### width
The width of this companion ad in pixels.
Type: number
Represents a single non-linear ad inside NonLinearAds.
#### adParameters
The ad parameters for this non-linear ad.
Type: string
#### apiFramework
The API framework used by this non-linear ad.
VAST 2.0 and 3.0 only.
Type: string
#### clickThrough
The click-through configuration for this non-linear ad.
Type: Click
#### clickTrackings
The click-tracking configurations for this non-linear ad.
#### expandedHeight
The expanded height of this non-linear ad in pixels.
VAST 2.0 and 3.0 only.
Type: number
#### expandedWidth
The expanded width of this non-linear ad in pixels.
VAST 2.0 and 3.0 only.
Type: number
#### height
The height of this non-linear ad in pixels.
VAST 2.0 and 3.0 only.
Type: number
#### id
The ID of this non-linear ad.
VAST 2.0 and 3.0 only.
Type: string
#### maintainAspectRatio
Whether this non-linear ad's aspect ratio should be maintained when scaled.
VAST 2.0 and 3.0 only.
Type: boolean
#### minSuggestedDuration
The minimum suggested duration of this non-linear ad in seconds.
VAST 2.0 and 3.0 only.
Type: number
#### resource
The resource associated with this non-linear ad.
Type: Resource
#### scalable
Whether this non-linear ad is meant to scale to larger dimensions.
VAST 2.0 and 3.0 only.
Type: boolean
#### width
The width of this non-linear ad in pixels.
VAST 2.0 and 3.0 only.
Type: number
Represents a linear within a Creative.
#### adParameters
The ad parameters for this linear creative.
Type: string
#### duration
The duration of this linear creative in seconds.
Type: number
#### icons
The icons for this linear creative.
#### interactiveCreativeFiles
The interactive creative files for this linear creative.
Type: Array<InteractiveCreativeFile>
#### mediaFiles
The media files for this linear creative.
#### mezzanine
The URI of the raw mezzanine file for this linear creative, intended for
video transcoding.
Type: string
#### skipoffset
The time interval after which this linear creative can be skipped.
Type: TimeOffset
#### trackingEvents
The event-tracking configuration for this linear creative.
Type: TrackingEvents
#### videoClicks
The video click tracking configuration for this linear creative.
Type: VideoClicks
Represents a VAST ad pod.
#### ads
The ads in this ad pod.
Type: SortedList
Stores information about the ad system.
#### name
The name of the ad server that returned the ad.
Type: string
#### version
The version of the ad system.
Type: string
Extends AbstractAd
Represents an InLine ad.
#### adTitle
The title for this ad.
Type: string
#### advertiser
The advertiser name for this ad.
Type: string
#### categories
The categories for this ad.
#### description
The description for this ad.
Type: string
#### surveys
The survey URI for this ad.
Extends AbstractAd
Represents a wrapper ad.
#### allowMultipleAds
Whether multiple ads are allowed in the requested VAST response.
Type: boolean
#### fallbackOnNoAd
Whether to use an available Ad when the requested VAST response returns no
ads.
Type: boolean
#### followAdditionalWrappers
Whether subsequent wrappers after a requested VAST response is allowed.
Type: boolean
#### vastAdTagURI
The URI to a VAST response that may be another VAST Wrapper or a
VAST InLine ad.
Type: string
Represents an icon used in a Linear creative.
#### apiFramework
The API framework used by this icon.
Type: string
#### clicks
The click-tracking configuration for this icon.
Type: IconClicks
#### duration
The duration of this icon in seconds.
Type: number
#### height
The height of this icon in pixels.
Type: number
#### offset
The time offset of this icon in seconds.
Type: number
#### program
The industry initiative that this icon supports.
Type: string
#### pxratio
The pixel ratio for which the icon creative is intended.
Type: string
#### resource
The resource associated with this icon.
Type: Resource
#### viewTrackings
The view-tracking URIs for this icon.
#### width
The width of this icon in pixels.
Type: number
#### xPosition
The horizontal position of this icon. Either a number of pixels or the
string "left" or "right".
#### yPosition
The vertical position of this icon. Either a number of pixels or the
string "top" or "bottom".
Represents a media file used in a Linear creative.
#### apiFramework
The API framework used by this media file.
Type: string
#### bitrate
The bitrate of this media file in kbps.
Type: number
#### codec
The codec of this media file in RFC 4281 format.
Type: string
#### delivery
The delivery method for this media file.
Type: string
#### height
The height of this media file in pixels.
Type: number
#### id
The ID of this media file.
Type: string
#### maintainAspectRatio
Whether this media file's aspect ratio should be maintained when scaled.
Type: boolean
#### maxBitrate
The maximum bitrate of this media file in kbps.
Type: number
#### minBitrate
The minimum bitrate of this media file in kbps.
Type: number
#### scalable
Whether this media file is meant to scale to larger dimensions.
Type: boolean
#### type
The MIME type of this media file.
Type: string
#### uri
The URI to this media file.
Type: string
#### width
The width of this media file in pixels.
Type: number
Represents an interactive creative file used in a Linear creative.
#### apiFramework
The API framework used by this interactive creative file.
Type: string
#### type
The MIME type of this interactive creative file.
Type: string
#### uri
The URI to this interactive creative file.
Type: string
Pricing information for real-time bidding.
#### authority
The URL for the organizational authority that produced the list being used
to identify the ad content.
Type: string
#### code
The category code or label that identifies the ad content.
Type: string
Describes a click configuration.
#### id
The ID of this click.
Type: string
#### uri
The URI of this tracking pixel.
Type: string
Represents companion ads within a Creative.
#### companions
The companion ads.
#### required
Determines which companion creative to display when multiple companions
are supplied and whether the ad can be displayed without its companion
creative. Either "all", "any", or "none".
Type: string
Extends AbstractExtension
Represents a creative extension.
Represents a unique identifier for an ad.
#### creativeIdentifier
The string identifying the unique creative identifier.
Type: string
#### idRegistry
The registry URL for the unique creative identifier.
Type: string
#### idValue
A string for the unique creative identifier.
Type: string
Extends AbstractResource
Describes non-HTML creative.
#### creativeType
The MIME type of this resource.
Type: string
Represents pricing information for real-time bidding.
#### currency
The three-letter ISO-4217 currency symbol that identifies the currency of
the value provided (e.g. "USD", "GBP", etc.).
Type: string
#### model
The pricing model. Either "CPM", "CPC", "CPE", or "CPV".
Type: string
#### value
The price that can be used in real-time bidding systems.
Type: number
Extends AbstractClicks
Represents the click-tracking configuration for a Linear creative.
#### customClicks
The custom-click configurations.
Extends AdBuffet
Represents a VAST document.
#### errors
The error-tracking URIs for this document.
#### uri
The URI associated with this document.
Type: string
#### version
The VAST version used by this document.
Type: number
Extends AbstractExtension
Represents a VAST extension.
Extends AbstractVerificationResource
Describes a Flash resource used to collect verification data.
Represents a list of verification resources for a vendor.
#### flashResources
The Flash resources for this verification vendor.
Type: Array<FlashResource>
#### javaScriptResources
The JavaScript resources for this verification vendor.
Type: Array<JavaScriptResource>
#### vendor
The home page URL for the verification service provider that supplies the
resource file.
Type: string
#### viewableImpression
The viewable impression for this verification vendor.
Type: ViewableImpression
Extends AbstractResource
Describes an HTML snippet.
Extends AbstractClicks
Represents the click tracking configuration for an Icon.
Represents the impression-tracking URIs for both an InLine and any
Wrapper.
#### id
The ad server ID of this viewability impression pixel.
Type: string
#### notViewables
The URIs that direct the video player to a tracking resource file that the
video player should request if the ad is executed but never meets criteria
for a viewable impression.
#### viewables
The URIs that direct the video player to a tracking resource file that the
video player should request at the time that criteria is met for a viewable
impression.
#### viewUndetermineds
The URIs that direct the video player to a tracking resource file that the
video player should request if the player cannot determine whether criteria
is met for a viewable impression.
Represents an impression.
#### id
The ad server id for the impression.
Type: string
#### uri
The URI of this impression resource.
Type: string
Extends AbstractResource
Describes an HTML page for display within an iframe.
Extends AbstractVerificationResource
Describes a JavaScript resource used to collect verification data.
Represents non-linear ads within a Creative.
#### nonLinears
The non-linear ads.
#### trackingEvents
The event-tracking configuration.
Type: TrackingEvents
Represents an event to be tracked.
#### offset
The time offset for this event configuration.
Type: TimeOffset
#### uri
The tracking URI for this event configuration.
Type: string
Extends AbstractTimeOffset
Represents a time offset expressed as a percentage (between 0 and 100).
Represents an item in a SortedList. Base class for Ad and
Creative.
#### sequence
The sequence number of this item within its parent.
Type: number
Represents survey information for data collection.
#### type
The MIME type of the resource being served.
Type: string
#### uri
The URI to any resource relating to an integrated survey.
Type: string
The main thing that's missing is validation. There are a few steps to this:
- Use validator to check all values
passed to setters.
- Verify that every required property is set.
- Write tests for the validation code.
- Enclose all validation code in marker comments (e.g., //
will allow us to strip it out and produce a lightweight "loose" build without
any validation, making tags load faster.
PRs welcome!
- Tim De Pauw
- Christophe Bonello
MIT