Skip to content

Latest commit

 

History

History
136 lines (101 loc) · 5.56 KB

parser.md

File metadata and controls

136 lines (101 loc) · 5.56 KB

VAST Parser

The VAST Parser is accessed through DMVAST.parser object.

Whenever an error occurs during the VAST parsing, the parser will call on his own all related tracking error URLs. Reported errors are:

  • no_ad: The VAST document is empty

  • VAST error 101: VAST schema validation error.

  • VAST error 301: Timeout of VAST URI provided in Wrapper element.

  • VAST error 302: Wrapper limit reached.

  • VAST error 303: No VAST response after one or more Wrappers.

Once the VAST document parsed, a callback method is called with an array VASTAd instances.

Methods

addURLTemplateFilter( replace )

Add the replace function at the end of the URLTemplateFilters array. All functions in URLTemplateFilters will be called with the VAST URL as parameter before fetching the VAST URL document.

DMVAST.parser.addURLTemplateFilter(function(vastUrl) {
    return url.replace('[DOMAIN]', 'mywebsite.com')
});
// For a VASTAdTagURI defined as :
// <VASTAdTagURI>http://example.dailymotion.com/vast.php?domain=[DOMAIN]</VASTAdTagURI>
// HTTP request will be:
// http://example.dailymotion.com/vast.php?domain=mywebsite.com

clearUrlTemplateFilters()

Reset URLTemplateFilters to empty, previous replace function set with addURLTemplateFilter() are no longer called.

DMVAST.parser.addURLTemplateFilter(function(vastUrl) {
    return url.replace('[DOMAIN]', 'mywebsite.com')
});

DMVAST.parser.clearUrlTemplateFilters();
// [DOMAIN] placeholder is no longer replaced

countURLTemplateFilters()

Returns how many replace function are set (ie: URLTemplateFilters length)

DMVAST.parser.addURLTemplateFilter(function(vastUrl) {
    return url.replace('[DOMAIN]', 'mywebsite.com')
});

DMVAST.parser.clearUrlTemplateFilters();
// return 1

load( xml [, options ], done )

Parse an VAST xml, resolve any wrappers and execute callback function done

  • String XMLDocument – A VAST XML document.

  • Object options – An optional set of key/value to configure the Ajax request:

    • Object urlhandler – A URL handler module, used to fetch VASTAdTagURI URL. If defined, will be used instead of the default ones.
    • Boolean withCredentials – A boolean to enable the withCredentials options for the XHR and FLASH URLHandlers.
    • Number wrapperLimit – A number of available Wrapper responses that can be received with no InLine response.

  • Function done – Method to be called once the VAST document is parsed. When at least 1 valid <inline> has been found, the 1st parameter will be an array of VASTAd instances. Hoverwise, in case of no ads, it will be null, and an error as a 2nd parameter is provided.

var xml = (new window.DOMParser()).parseFromString(xmlStr, "text/xml");
var options = {
    withCredentials : true,
    wrapperLimit : 5
};

DMVAST.parser.load(xml, options, function(response, error) {
  // process the VAST response
});

on( eventName, listener)

Add the listener function for the event named eventName. eventName value can be :

  • String VAST-error – emitted when the parser encountered a VAST error (ie: no ads, warapper timeout...). The VAST error code is passed to the listener function as a parameter.
DMVAST.parser.on(`VAST-error`, function(error) {
    console.log('error:', error)
});

// Parsing a no ad VAST xml document
DMVAST.parser.load(xmlNoAds, options, function(response, error) {});
// Will log => "error: {ERRORCODE: 303}""

once( eventName, listener)

Add a one time listener function for the event named eventName.

parse( url [, options ], done )

Fetch a URL and parse the response into a valid VAST object.

  • String url – The VAST XML document URL to fetch.

  • Object options – An optional set of key/value to configure the Ajax request:

    • Object urlhandler – A URL handler module, used to fetch the VAST document instead of the default ones.
    • Boolean withCredentials – A boolean to enable the withCredentials options for the XHR and FLASH URLHandlers.
    • Number wrapperLimit – A number of available Wrapper responses that can be received with no InLine response.

  • Function done – Method to be called once the VAST document is parsed. When at least 1 valid <inline> has been found, the 1st parameter will be an array of VASTAd instances. Hoverwise, in case of no ads, it will be null, and an error as a 2nd parameter is provided.

var url = 'http://example.dailymotion.com/vast.xml';
var options = {
    withCredentials : true,
    wrapperLimit : 5
};

DMVAST.parser.parse(url, options, function(response, error) {
  // process the VAST response
});

off( eventName, listener )

Remove the specified listener for the event named eventName.

removeURLTemplateFilter( replace )

Remove replace function from URLTemplateFilters array. replace function won't be called on the next VAST URL encountred by the parser.

var replaceDomain = function() {
    return url.replace('[DOMAIN]', 'mywebsite.com')
};

DMVAST.parser.addURLTemplateFilter(replaceDomain);
// ...
DMVAST.parser.removeURLTemplateFilter(replaceDomain);
// [DOMAIN] placeholder is no longer replaced