Skip to content

Latest commit

 

History

History
116 lines (72 loc) · 3.39 KB

README.md

File metadata and controls

116 lines (72 loc) · 3.39 KB
Raw

@unruly/vast-parser

Travis npm

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.

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.