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's sequence attribute and automatically orders elements by its value.

• Elements that are not required are null by default. A typical example is TrackingEvents on the ads in a Creative.

API

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

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.

Type: Array<string>

extensions

The extensions for this ad.

Type: Array<Extension>

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.

Type: Array<Click>

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.

Type: Array<string>

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.

Type: Array<Click>

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.

Type: Array<Click>

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.

Type: Array<Icon>

interactiveCreativeFiles

The interactive creative files for this linear creative.

Type: Array<InteractiveCreativeFile>

mediaFiles

The media files for this linear creative.

Type: Array<MediaFile>

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.

Type: Array<Category>

description

The description for this ad.

Type: string

surveys

The survey URI for this ad.

Type: Array<Survey>

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.

Type: Array<string>

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

Type: (number | string)

yPosition

The vertical position of this icon. Either a number of pixels or the string "top" or "bottom".

Type: (number | string)

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.

Type: Array<Companion>

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.

Type: Array<Click>

VAST

Extends AdBuffet

Represents a VAST document.

errors

The error-tracking URIs for this document.

Type: Array<string>

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.

Type: Array<string>

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.

Type: Array<string>

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.

Type: Array<string>

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.

Type: Array<NonLinear>

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

• Tim De Pauw
• Christophe Bonello

License

MIT