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