@unruly/vast-parser

Recursively requests and parses VAST chains into a single JavaScript object.

VAST Chains are VAST Wrappers wrapped in more VAST Wrappers eventually resulting in a VAST Inline.

Example

import { VastAdManager } from '@unruly/vast-parser'

const vastAdManager = new VastAdManager()
vastAdManager.requestVastChain({ url: 'http://example.com/vast-file.xml' })
  .then(
    vastResponse => {
      // success
    },
    vastError => {
      // failure
    }
  )

Installation

You'll need to use a package manager like npm to install this package.

# npm
npm install @unruly/vast-parser

# yarn
yarn add @unruly/vast-parser

Notable Dependencies

• jQuery for requesting nested VAST URIs. We hope to replace this in the future.

Polyfills

You may need to include some polyfills depending on your target environment.

• Promise
• URL

Usage

Use this package like a typical ES6 module. For detailed usage information on each export, see the subsections below.

// import what you need
import {
  VastAdManager,
  VastErrorCodes,
  VastParser
} from '@unruly/vast-parser'

// do what you want

VastAdManager

new VastAdManager(): { requestVastChain, addEventListener }

Creates a VastAdManager.

vastAdManager.requestVastChain(config: ({ url: string })): Promise

Recursively requests a given VAST URL until a VAST Inline is reached.

Resolves to a VastResponse.

Rejects to a VastError with a code matching to one of the VastErrorCodes.code (see VastErrorCodes section).

vastAdManager.addEventListener(eventName: string, handler: (event: Event) => void): void

Calls the given handler when an event of the eventName is fired. The handler is passed the event as its first parameter.

Event Names

• requestStart - start of request for VAST file
• requestEnd - end of request for VAST file

Event Properties

• requestNumber - the current depth of the VAST chain.
• uri - the URI for the request.
• vastResponse - the VastResponse by being built reference.

Caveats

• VastAdManager currently does not support NodeJS as it relies on jQuery.

VastErrorCodes

An Enum of possible error codes on a VastError (see vastAdManager.requestVastChain section).

For possible values, see the module.

VastParser

VastParser.parse(doc: (Document | { xml: string })): Document

Parses a given VAST document into a JSXMLNode. JSXMLNode a simple JS representation of an XML document.

Caveats

• To work in NodeJS, you'll need to pass a Document. Use a library like xmldom to parse your document string before sending it to VastParser.parse.

License

License information can be found in the LICENSE file.