Skip to main content
Type definitions for parsing and handling VAST (Video Ad Serving Template) 4.x responses.
These types conform to the IAB VAST 4.x specification. For more information, see the official VAST documentation.

​
VASTResponse

Root VAST response structure returned by the parser. 
interface VASTResponse {
  version: string;
  ads: Ad[];
  errors: string[];
}
​
version
string
VAST version from the XML (e.g., “4.0”, “4.1”, “4.2”).
​
ads
Ad[]
Array of parsed Ad elements from the VAST response.
​
errors
string[]
Error tracking URLs from the VAST document.
Represents a single ad element. Can be either inline or wrapper. 
interface Ad {
  id: string;
  sequence?: number;
  adSystem?: AdSystem;
  adTitle?: string;
  impressions: Impression[];
  creatives: Creative[];
  errors: string[];
  wrapper?: Wrapper;
  inLine?: InLine;
}
​
id
string
Unique identifier for the ad.
​
sequence
number
Playback sequence for ad pods. Lower numbers play first.
​
adSystem
AdSystem
Information about the ad server. See AdSystem.
​
adTitle
string
Title of the advertisement.
​
impressions
Impression[]
Impression tracking URLs. See Impression.
​
creatives
Creative[]
Creative elements (linear, non-linear, companion). See Creative.
​
errors
string[]
Error tracking URLs specific to this ad.
​
wrapper
Wrapper
Present if this is a wrapper ad that points to another VAST tag. See Wrapper.
​
inLine
InLine
Present if this is an inline ad with direct creative content. See InLine.

​
AdSystem

Identifies the ad server that returned the ad. 
interface AdSystem {
  name: string;
  version?: string;
}
​
name
string
Name of the ad server system.
​
version
string
Version of the ad server.

​
InLine

Inline ad content with direct creative elements. 
interface InLine {
  adTitle: string;
  description?: string;
  advertiser?: string;
  pricing?: Pricing;
  survey?: string;
  category?: Category[];
  creatives: Creative[];
}
​
adTitle
string
Title of the advertisement.
​
description
string
Description of the ad content.
​
advertiser
string
Name of the advertiser.
​
pricing
Pricing
Pricing information. See Pricing.
​
survey
string
URL to an optional survey.
​
category
Category[]
Content categories. See Category.
​
creatives
Creative[]
Creative elements for this inline ad.

​
Wrapper

Wrapper ad that redirects to another VAST tag. 
interface Wrapper {
  vastAdTagURI: string;
  followAdditionalWrappers?: boolean;
  allowMultipleAds?: boolean;
  fallbackOnNoAd?: boolean;
}
​
vastAdTagURI
string
URL to the wrapped VAST tag.
​
followAdditionalWrappers
boolean
Whether to follow additional wrapper redirects.
​
allowMultipleAds
boolean
Whether multiple ads are allowed in the wrapped response.
​
fallbackOnNoAd
boolean
Whether to use fallback if wrapped VAST returns no ads.

​
Impression

Impression tracking pixel URL. 
interface Impression {
  id?: string;
  url: string;
}
​
id
string
Optional identifier for the impression.
​
url
string
Impression tracking URL to fire when ad is displayed.

​
Creative

Creative element containing linear video, non-linear overlays, or companion ads. 
interface Creative {
  id?: string;
  sequence?: number;
  adId?: string;
  linear?: Linear;
  nonLinearAds?: NonLinearAd[];
  companionAds?: CompanionAd[];
}
​
id
string
Unique identifier for the creative.
​
sequence
number
Playback sequence for multiple creatives.
​
adId
string
Reference to the parent ad ID.
​
linear
Linear
Linear video creative. See Linear.
​
nonLinearAds
NonLinearAd[]
Non-linear overlay ads. See NonLinearAd.
​
companionAds
CompanionAd[]
Companion banner ads. See CompanionAd.

​
Linear

Linear video creative with media files and tracking. 
interface Linear {
  duration: number;
  skipOffset?: number;
  mediaFiles: MediaFile[];
  trackingEvents: TrackingEvent[];
  videoClicks?: VideoClicks;
  adParameters?: string;
  icons?: Icon[];
}
​
duration
number
Total duration of the video in seconds.
​
skipOffset
number
Time in seconds after which skip button becomes available.
​
mediaFiles
MediaFile[]
Available media file options. See MediaFile.
​
trackingEvents
TrackingEvent[]
Tracking URLs for various playback events. See TrackingEvent.
​
videoClicks
VideoClicks
Click tracking and click-through URLs. See VideoClicks.
​
adParameters
string
Custom parameters to pass to the creative.
​
icons
Icon[]
Icon overlays (e.g., AdChoices). See Icon.

​
MediaFile

Video file reference with codec and quality information. 
interface MediaFile {
  id?: string;
  url: string;
  delivery: 'progressive' | 'streaming';
  type: string;
  width: number;
  height: number;
  bitrate?: number;
  minBitrate?: number;
  maxBitrate?: number;
  scalable?: boolean;
  maintainAspectRatio?: boolean;
  codec?: string;
  apiFramework?: string;
}
​
id
string
Optional identifier for the media file.
​
url
string
URL to the video file.
​
delivery
'progressive' | 'streaming'
Delivery method: progressive (HTTP download) or streaming (HLS/DASH).
​
type
string
MIME type with optional codec (e.g., video/mp4, video/mp4; codecs="avc1.42E01E").
​
width
number
Video width in pixels.
​
height
number
Video height in pixels.
​
bitrate
number
Target bitrate in kbps.
​
minBitrate
number
Minimum bitrate for adaptive streaming.
​
maxBitrate
number
Maximum bitrate for adaptive streaming.
​
scalable
boolean
Whether the media file can be scaled.
​
maintainAspectRatio
boolean
Whether to maintain aspect ratio when scaling.
​
codec
string
Video codec identifier.
​
apiFramework
string
API framework required for playback (e.g., “VPAID”).

​
TrackingEvent

Tracking URL for specific playback events. 
interface TrackingEvent {
  event: TrackingEventType;
  url: string;
  offset?: number;
}
​
event
TrackingEventType
Type of event to track. See TrackingEventType.
​
url
string
Tracking pixel URL to fire when event occurs.
​
offset
number
Time offset in seconds for progress events.

​
TrackingEventType

Supported tracking event types per VAST 4.x specification. 
type TrackingEventType =
  | 'creativeView'
  | 'start'
  | 'firstQuartile'
  | 'midpoint'
  | 'thirdQuartile'
  | 'complete'
  | 'mute'
  | 'unmute'
  | 'pause'
  | 'resume'
  | 'rewind'
  | 'skip'
  | 'playerExpand'
  | 'playerCollapse'
  | 'progress'
  | 'closeLinear'
  | 'loaded'
  | 'impression'
  | 'error';
Standard VAST tracking events for video playback analytics.

​
VideoClicks

Click tracking and click-through URL configuration. 
interface VideoClicks {
  clickThrough?: ClickThrough;
  clickTracking?: ClickTracking[];
  customClick?: CustomClick[];
}
​
clickThrough
ClickThrough
Primary click-through destination. See ClickThrough.
​
clickTracking
ClickTracking[]
Click tracking pixels. See ClickTracking.
​
customClick
CustomClick[]
Custom click tracking URLs. See CustomClick.

​
ClickThrough

Primary click-through URL for the ad. 
interface ClickThrough {
  id?: string;
  url: string;
}
​
id
string
Optional identifier.
​
url
string
Landing page URL when user clicks the ad.

​
ClickTracking

Click tracking pixel URL. 
interface ClickTracking {
  id?: string;
  url: string;
}
​
id
string
Optional identifier.
​
url
string
Tracking URL to fire when ad is clicked.

​
CustomClick

Custom click tracking URL. 
interface CustomClick {
  id?: string;
  url: string;
}
​
id
string
Optional identifier.
​
url
string
Custom tracking URL.

​
NonLinearAd

Non-linear overlay ad (banner over video). 
interface NonLinearAd {
  id?: string;
  width: number;
  height: number;
  minSuggestedDuration?: number;
  staticResource?: string;
  iFrameResource?: string;
  htmlResource?: string;
  nonLinearClickThrough?: string;
  trackingEvents: TrackingEvent[];
}
​
id
string
Optional identifier.
​
width
number
Width in pixels.
​
height
number
Height in pixels.
​
minSuggestedDuration
number
Minimum suggested display duration in seconds.
​
staticResource
string
URL to static image resource.
​
iFrameResource
string
URL to iframe resource.
​
htmlResource
string
HTML content as string.
​
nonLinearClickThrough
string
Click-through URL for the overlay.
​
trackingEvents
TrackingEvent[]
Tracking events for the overlay.

​
CompanionAd

Companion banner ad displayed alongside video. 
interface CompanionAd {
  id?: string;
  width: number;
  height: number;
  staticResource?: string;
  iFrameResource?: string;
  htmlResource?: string;
  companionClickThrough?: string;
  trackingEvents: TrackingEvent[];
}
​
id
string
Optional identifier.
​
width
number
Width in pixels.
​
height
number
Height in pixels.
​
staticResource
string
URL to static image resource.
​
iFrameResource
string
URL to iframe resource.
​
htmlResource
string
HTML content as string.
​
companionClickThrough
string
Click-through URL for the companion ad.
​
trackingEvents
TrackingEvent[]
Tracking events for the companion ad.

​
Icon

Icon overlay (e.g., AdChoices icon). 
interface Icon {
  program?: string;
  width: number;
  height: number;
  xPosition: string | number;
  yPosition: string | number;
  duration?: number;
  offset?: number;
  staticResource?: string;
  iFrameResource?: string;
  htmlResource?: string;
  iconClicks?: IconClicks;
}
​
program
string
Industry initiative program (e.g., “AdChoices”).
​
width
number
Width in pixels.
​
height
number
Height in pixels.
​
xPosition
string | number
Horizontal position (pixel value or “left”/“right”).
​
yPosition
string | number
Vertical position (pixel value or “top”/“bottom”).
​
duration
number
Display duration in seconds.
​
offset
number
Time offset in seconds when icon should appear.
​
staticResource
string
URL to static image resource.
​
iFrameResource
string
URL to iframe resource.
​
htmlResource
string
HTML content as string.
​
iconClicks
IconClicks
Click handling for the icon. See IconClicks.

​
IconClicks

Click handling for icon overlays. 
interface IconClicks {
  iconClickThrough?: string;
  iconClickTracking?: string[];
}
​
iconClickThrough
string
Click-through URL for the icon.
​
iconClickTracking
string[]
Click tracking URLs for the icon.

​
Pricing

Pricing model information. 
interface Pricing {
  model: 'cpm' | 'cpc' | 'cpe' | 'cpv';
  currency: string;
  value: number;
}
​
model
'cpm' | 'cpc' | 'cpe' | 'cpv'
Pricing model:
  • cpm - Cost per thousand impressions
  • cpc - Cost per click
  • cpe - Cost per engagement
  • cpv - Cost per view
​
currency
string
Currency code (e.g., “USD”, “EUR”).
​
value
number
Price value in the specified currency.

​
Category

Content category classification. 
interface Category {
  authority?: string;
  value: string;
}
​
authority
string
Authority defining the category taxonomy.
​
value
string
Category value.

​
VASTErrorCode

Standard VAST error codes per IAB specification. 
enum VASTErrorCode {
  XML_PARSING_ERROR = 100,
  VAST_SCHEMA_VALIDATION_ERROR = 101,
  VAST_VERSION_NOT_SUPPORTED = 102,
  GENERAL_WRAPPER_ERROR = 300,
  WRAPPER_TIMEOUT = 301,
  WRAPPER_LIMIT_REACHED = 302,
  NO_VAST_RESPONSE = 303,
  GENERAL_LINEAR_ERROR = 400,
  FILE_NOT_FOUND = 401,
  MEDIA_TIMEOUT = 402,
  MEDIA_NOT_SUPPORTED = 403,
  GENERAL_COMPANION_ERROR = 600,
  UNDEFINED_ERROR = 900
}
​
XML_PARSING_ERROR
100
Failed to parse VAST XML.
​
VAST_SCHEMA_VALIDATION_ERROR
101
VAST XML does not conform to schema.
​
VAST_VERSION_NOT_SUPPORTED
102
VAST version is not supported by the player.
​
GENERAL_WRAPPER_ERROR
300
General wrapper ad error.
​
WRAPPER_TIMEOUT
301
Wrapper ad request timed out.
​
WRAPPER_LIMIT_REACHED
302
Maximum wrapper depth exceeded.
​
NO_VAST_RESPONSE
303
No VAST response received from wrapper.
​
GENERAL_LINEAR_ERROR
400
General linear creative error.
​
FILE_NOT_FOUND
401
Media file not found or failed to load.
​
MEDIA_TIMEOUT
402
Media file request timed out.
​
MEDIA_NOT_SUPPORTED
403
No supported media files available.
​
GENERAL_COMPANION_ERROR
600
General companion ad error.
​
UNDEFINED_ERROR
900
Undefined error occurred.

Build docs developers (and LLMs) love

Get started for freeTalk to us