iab-vast-model
v1.0.2
Published
Base classes for IAB VAST handling.
Downloads
4,901
Maintainers
Keywords
Readme
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.
Usage
import { VAST } from 'iab-vast-model'
const vast = new VAST()
// ... Do your thing ...
Rationale
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
<Creatives>
,<CreativeExtensions>
,<Extensions>
,<MediaFiles>
and<Verifications>
. 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'ssequence
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 aCreative
.
API
Table of Contents
- AbsoluteTimeOffset
- AbstractAd
- AbstractClicks
- AbstractExtension
- AbstractResource
- AbstractTimeOffset
- AbstractVerificationResource
- AdBuffet
- SortedList
- TrackingEvents
- Creative
- Companion
- NonLinear
- Linear
- AdPod
- AdSystem
- InLine
- Wrapper
- Icon
- MediaFile
- InteractiveCreativeFile
- Category
- Click
- CompanionAds
- CreativeExtension
- UniversalAdId
- StaticResource
- Pricing
- VideoClicks
- VAST
- Extension
- FlashResource
- Verification
- HTMLResource
- IconClicks
- ViewableImpression
- Impression
- IFrameResource
- JavaScriptResource
- NonLinearAds
- TrackingEvent
- RelativeTimeOffset
- SortedListItem
- Survey
AbsoluteTimeOffset
Extends AbstractTimeOffset
Represents a time offset expressed as an absolute duration in seconds.
AbstractAd
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
AbstractClicks
Stores the click-through URI and a set of click-tracking pixels.
clickThrough
The click-through configuration.
Type: Click
clickTrackings
The click-tracking configurations.
AbstractExtension
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 <Extension>
XML DOM element.
Type: Element
AbstractResource
Base class for a verification resource used by a HTMLResource, a IFrameResource and a StaticResource.
uri
The URI to this resource.
Type: string
AbstractTimeOffset
Represents a time offset.
value
The value for this offset.
Type: number
AbstractVerificationResource
Extends AbstractResource
Base class for a verification resource used by a FlashResource and a JavaScriptResource.
apiFramework
The name of the API framework.
Type: string
AdBuffet
Represents a VAST ad buffet.
adPod
The ad pod for this ad buffet.
Type: AdPod
ads
The ads in this ad buffet.
Type: SortedList
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.
TrackingEvents
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.
Creative
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
Companion
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
NonLinear
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
Linear
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
AdPod
Represents a VAST ad pod.
ads
The ads in this ad pod.
Type: SortedList
AdSystem
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
InLine
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.
Wrapper
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
Icon
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"
.
MediaFile
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
InteractiveCreativeFile
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
Category
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
Click
Describes a click configuration.
id
The ID of this click.
Type: string
uri
The URI of this tracking pixel.
Type: string
CompanionAds
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
CreativeExtension
Extends AbstractExtension
Represents a creative extension.
UniversalAdId
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
StaticResource
Extends AbstractResource
Describes non-HTML creative.
creativeType
The MIME type of this resource.
Type: string
Pricing
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
VideoClicks
Extends AbstractClicks
Represents the click-tracking configuration for a Linear creative.
customClicks
The custom-click configurations.
VAST
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
Extension
Extends AbstractExtension
Represents a VAST extension.
FlashResource
Extends AbstractVerificationResource
Describes a Flash resource used to collect verification data.
Verification
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
HTMLResource
Extends AbstractResource
Describes an HTML snippet.
IconClicks
Extends AbstractClicks
Represents the click tracking configuration for an Icon.
ViewableImpression
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.
Impression
Represents an impression.
id
The ad server id for the impression.
Type: string
uri
The URI of this impression resource.
Type: string
IFrameResource
Extends AbstractResource
Describes an HTML page for display within an iframe.
JavaScriptResource
Extends AbstractVerificationResource
Describes a JavaScript resource used to collect verification data.
NonLinearAds
Represents non-linear ads within a Creative.
nonLinears
The non-linear ads.
trackingEvents
The event-tracking configuration.
Type: TrackingEvents
TrackingEvent
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
RelativeTimeOffset
Extends AbstractTimeOffset
Represents a time offset expressed as a percentage (between 0 and 100).
SortedListItem
Represents an item in a SortedList. Base class for Ad and Creative.
sequence
The sequence number of this item within its parent.
Type: number
Survey
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
TODO
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.,
// <strict>
). This will allow us to strip it out and produce a lightweight "loose" build without any validation, making tags load faster.
PRs welcome!
Maintainers
License
MIT