iab-vast-model

v1.0.2

Published

4 months ago

Base classes for IAB VAST handling.

Downloads

5,425

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

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

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.

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

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

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

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

iab-vast-model

Usage

Rationale

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