tbuchok / vast-xml Goto Github PK

A Node module for creating real-time VAST XML responses.

JavaScript 100.00%

vast-xml's Introduction

vast-xml

npm install vast-xml

Create a VAST object:

var VAST = require('vast-xml');

var vast = new VAST();
var ad = vast.attachAd({ 
      id : 1
    , structure : 'inline'
    , sequence : 99
    , Error: 'http://error.err'
    , AdTitle : 'Common name of the ad'
    , AdSystem : { name: 'Test Ad Server', version : '1.0' }
  });

Ad extensions

var VAST = require('vast-xml');

var vast = new VAST();
var ad = vast.attachAd({ 
      id : 1
    , structure : 'inline'
    , sequence : 99
    , Error: 'http://error.err'
    , Extensions: ['<xml>data</xml>'] // accepts an array or string of XML, warning: XML is not validated by this library!
    , AdTitle : 'Common name of the ad'
    , AdSystem : { name: 'Test Ad Server', version : '1.0' }
  });

Attach Impression tracking URLs

ad.attachImpression({
      id: "23"
    , url: "http://impression.com"
  });
ad.attachImpression({
      id: "sample-server"
    , url: "http://sample-impression.com"
  });

Attach Linear creatives

var creative = ad.attachCreative('Linear', {
    AdParameters : '<xml></xml>'
  , Duration : '00:00:30'
});
creative.attachMediaFile('http://domain.com/file.ext', {
    type: "video/mp4"
  , bitrate: "320"
  , minBitrate: "320"
  , maxBitrate: "320"
  , width: "640"
  , height: "360"
  , scalable: "true"
  , maintainAspectRatio: "true"
  , codec: ""
  , apiFramework: "VPAID"
});
creative.attachTrackingEvent('creativeView', 'http://creativeview.com');
creative.attachVideoClick('ClickThrough', 'http://click-through.com');

Skippable Linear Creatives

Create skippable linear creative by adding a skipoffset attribute when attaching creative. Attach skip and/or progress tracking events. See below:

var creative = ad.attachCreative('Linear', {
    AdParameters : '<xml></xml>'
  , skipoffset: '00:00:05'
  , Duration : '00:00:30'
});
// ...
creative.attachTrackingEvent('skip', 'http://skipevent.com');
creative.attachTrackingEvent('progress', 'http://zing-zang.com', '00:00:15.000');

Attach Icons to Linear creatives

var icon = creative.attachIcon({ 
    program : 'foo'
  , height : 250
  , width : 300
  , xPosition : 'left'
  , yPosition : 'top'
  , apiFramework : 'VPAID'
  , offset : '01:05:09'
  , duration : '00:00:00'
});
icon.attachResource('StaticResource', 'http://domain.com/file.gif', 'image/gif');
icon.attachClick('IconClickThrough', 'http://icon-click-through.com');
icon.attachTrackingEvent('IconViewTracking', 'http://icon-view-tracking.com');

Attach Non-Linear creatives

var creative = ad.attachCreative('NonLinear', {
    id : 99
  , width : 90
  , height: 10
  , expandedWidth : 90
  , expandedHeight : 45
  , scalable : false
  , maintainAspectRatio : false
  , minSuggestedDuration : '00:00:00'
  , apiFramework : 'VPAID'
});

Attach Companion Ad creatives

var creative = ad.attachCreative('CompanionAd', { width : 300 , height : 250 })
    .attachResource('StaticResource', 'http://companionad.com/image.jpg', 'image/jpeg')
    .attachTrackingEvent('creativeView', 'http://companionad.com/creativeView')
;

Generate XML

vast.xml({ pretty : true, indent : '  ', newline : '\n' });

<?xml version="1.0" encoding="UTF-8"?>
<VAST version="3.0">
  <Ad id="1" sequence="99">
    <InLine>
      <AdSystem version="1.0">Test Ad Server</AdSystem>
      <AdTitle>Common name of the ad</AdTitle>
      <Description/>
      <Survey/>
      <Error><![CDATA[http://error.err]]></Error>
      <Impression id="23">http://impression.com</Impression>
      <Impression id="sample-server">http://sample-impression.com</Impression>
      <Creatives>
        <Creative>
          <Linear>
            <Duration>00:00:00</Duration>
            <TrackingEvents>
              <Tracking event="creativeView">http://creativeview.com</Tracking>
            </TrackingEvents>
            <VideoClicks>
              <ClickThrough id="">http://click-through.com</ClickThrough>
            </VideoClicks>
            <MediaFiles>
              <MediaFile id="" delivery="progressive" type="video/mp4" bitrate="320" minBitrate="320" maxBitrate="320" width="640" height="360" scalable="true" maintainAspectRatio="true" codec="" apiFramework="">http://domain.com/file.ext</MediaFile>
            </MediaFiles>
          </Linear>
        </Creative>
        <Creative>
          <CompanionAds>
            <Companion width="300" height="250">
              <StaticResource creativeType="image/jpeg">http://companionad.com/image.jpg</StaticResource>
              <TrackingEvents>
                <Tracking event="creativeView">http://companionad.com/creativeView</Tracking>
              </TrackingEvents>
            </Companion>
          </CompanionAds>
        </Creative>
      </Creatives>
    </InLine>
  </Ad>
</VAST>

VAST with no ads

var VAST = require('vast-xml');

var vast = new VAST({VASTErrorURI: 'http://adserver.com/noad.gif'});
vast.xml({ pretty : true, indent : '  ', newline : '\n' });

<?xml version="1.0" encoding="UTF-8"?>
<VAST version="3.0">
  <Error>
    <![CDATA[http://adserver.com/noad.gif]>
  </Error>
</VAST>

Validating

npm test validates the test builds. The validation is done against the VAST .xsd file, made available by the IAB.

Currently included in the test suite are:

linear ad

with companion
with icon

non-linear ad

with companion

wrapper ad

The VAST spec is, well vast, and contains a lot of different corner cases.

Pull requests, feedback and collaboration in fully rounding-out this module is more than welcome.

Misc

xmllint is a good tool for validating XML. As a helper, this repo contains the VAST .xsd and to validate a VAST file, follow:

$ xmllint --noout --schema ./test/files/vast3_draft.xsd /path/to/the/vast.xml

vast-xml's People

Contributors

Stargazers

Watchers

vast-xml's Issues

AdTitle for wrapper ad?

Hey just wondering if you think that having the AdTitle in the wrapper ads would be a good addition?

Again, it's just something small I noticed- no AdTitle is generated in a wrapper ad even if specified...

VMAP support

I know this project is called vast-xml, but I'm wondering if VMAP support could be added.

Chaining #addImpression from an ad is doesn't return the `ad` object to continue

Add support for Non-linear Creatives

Cannot generate error

Hey so I'm wondering if it's possible to generate a vast xml with an error and all of the other fields (i.e. ad -> inline -> adsystem, adtitle, creatives, etc).

As of right now I can only generate the vast xml with an error by doing this

vast = new VAST({VASTErrorURI : "my.url.com"})

vast = new VAST({version : '2.0', VASTErrorURI : "my.url.com" })

it's working as expected. I'm going to try to remove a few of the function calls but as of right now I'm setting the ad, impression, creative, mediafile and it's not letting me set the error (it doesn't show in the xml) and the console is showing this

{ [Error: connect ECONNREFUSED]
   code: 'ECONNREFUSED',
   errno: 'ECONNREFUSED',
   syscall: 'connect' }

Error elements within a wrapper ad

When creating a vast xml response for wrapper ads, setting error does not generate an error element

ad = vast.attachAd({
  id : "theID"
 , structure : 'wrapper'
 , AdSystem : { name : 'AdSys', version : '2.0' }
 , AdTitle : 'WrapperAd'
 , Error : "http://the.error.com/err" // this line does not generate error element
 , VASTAdTagURI : vastResponseURL
});

Add support for Icon element(s)

Companion banner example doesn't work

Hey,

The readme example doesn't create a correct companion element, it only has the width and height.

The test code for companions works, although I can't figure out how to get the tracking events to be attached.

Add to NPM registry

Review human-readable docs and ensure all required elements are in place

Store `attributes` on elements directly, don't use XML builder to handle which to include

Feels awkward to include impressions in two different ways

Consider throwing errors when the VAST XML is created, and turning this off by default? Perhaps actually validating at that time, as well?

ad-level errors

allow for each ad in the vast response to have an optional error element

Custom element support?

Hello again,

Just wondering if there is any interest in supporting custom elements. For example, if I wanted to have an esi tag,

<VAST version="3.0">
  <esi:vars>
...
  </esi:vars>
</VAST>

I know that's probably going to fail the vast validation, but I think it would definitely be useful to have..

Any thoughts?

No `AdParameters` present must be accounted for

Backward compatability for VAST 2.0?

Hello again,

Just wondering if when I specify vast version 2.0 if that is actually doing anything/generating a vast document that is compatible with 2.0. I'm just wondering that if I'm overwriting the version - e.g.
var VAST = require('vast-xml')
, vast = new VAST({version : '2.0'});

which is correctly displaying in the generated vast xml -
if this is actually doing anything to prevent nodes that may be only available in vast 3.0?

Great package btw.

Allow for multiple Surveys

Merge settings into already-initialized `attributes` object

Consider within all files that receives settings and needs to set attributes.

How to save the xml as a file?

Pretty basic question, but couldn't seem to find an answer (doesn't help that I'm new to node.js)

Just wondering what I should look into for saving this xml as a file on my server/downloading it after creation - Would the best way be to do something like this

fs.writeFile('message.txt', vast.xml({ pretty : true, indent : ' ', newline : '\n' }), function (err) {
if (err) throw err;
});

Just kind of thinking out loud at this point, but is there something built into this package that I can use.. I.e.

vast.saveFile('/location/to/save');

HTML entities automatically generated

I was wondering if there was a way to configure the library not to convert my VASTAdTagURI from the original string to one with html entitites?

For example when I do

ad.attachImpression({
  id: "impression",
  url: "http://foo.bar.com/p<esi:vars></esi:vars>";

it changes it to

<VASTAdTagURI>http://foo.bar.com/p&lt;esi:vars&gt;&lt;/esi:vars&gt;</VASTAdTagURI>

When I'd rather be getting

<VASTAdTagURI>http://foo.bar.com/p<esi:vars></esi:vars></VASTAdTagURI>