vast-player
v0.2.10
Published
Playback VAST creatives in a web browser.
Downloads
1,193
Maintainers
minznerjoshReadme
vast-player
Vast-Player makes it easy to playback linear VAST creatives in the browser. It currently supports VPAID 1.0/2.0 (JavaScript and Flash) and HTML5 <MediaFile>s. The library has the following responsibilites:
- Requesting VAST ad tags
- Resolving VAST wrapper tags
- Choosing a
<MediaFile>based on the browser environment - Loading/initializing a
<MediaFile>(including VPAID creatives) - Firing VAST tracking pixels/impressions at the correct time
- Opening VAST
<VideoClicks>when appropriate
Example
<!DOCTYPE html>
<html>
<head>
<title>Vast-Player Example</title>
<script src="https://cdn.jsdelivr.net/npm/vast-player@latest/dist/vast-player.min.js"></script>
<style>
#container {
width: 640px; height: 385px;
position: relative;
}
</style>
</head>
<body>
<div id="container"></div>
<script>
(function(VASTPlayer) {
'use strict';
var player = new VASTPlayer(document.getElementById('container'));
player.once('AdStopped', function() {
console.log('Ad finished playback!');
});
player.load(
'https://platform-staging.reelcontent.com/api/public/vast/2.0/tag?campaign=cam-e951792a909f17'
).then(function startAd() {
return player.startAd();
}).catch(function(reason) {
setTimeout(function() { throw reason; }, 0);
});
}(window.VASTPlayer));
</script>
</body>
</html>Adding to Project
via npm (with browserify)
Install as a dependency
$> npm install vast-player --saveUse the module
var VASTPlayer = require('vast-player'); var player = new VASTPlayer(document.getElementById('container')); player.load('https://www.myadserver.com/mytag');
via RequireJS
Add to RequireJS config
requirejs.config({ paths: { VASTPlayer: 'https://cdn.jsdelivr.net/npm/[email protected]/dist/vast-player.min.js' } });Use the module
define(['VASTPlayer'], function(VASTPlayer) { var player = new VASTPlayer(document.getElementById('container')); player.load('https://www.myadserver.com/mytag'); });
via a <script>
Add a
<script>to the page<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/vast-player.min.js"></script>Use the module
var player = new window.VASTPlayer(document.getElementById('container')); player.load('https://www.myadserver.com/mytag');
API
main exports
VASTPlayer(container:Node, [config]:Object) extends EventEmitter
- Parameters
- container:
Node: A DOM node into which the ad will be inserted. The ad will take up 100% of the width and height of the container. - optional config:
Object: The following properties are supported- config.vast:
Object: Configuration for fetching VAST ad tags- config.vast.resolveWrappers:
Boolean:trueif VAST<Wrapper>s should be fetched automatically. Defaults totrue. - config.vast.maxRedirects:
Number: The number of VAST<Wrapper>s that are allowed to be fetched. Defaults to5.
- config.vast.resolveWrappers:
- config.tracking:
Object: Configuration for firing tracking pixels- config.tracking.mapper:
Function: ThisFunctioncan be used to transform the URIs of VAST tracking pixels. TheFunctionwill be invoked every time a tracking pixel is fired, with the URI of the pixel as the only argument. The returnedStringURI will be fired. Deaults to an identityFunction.
- config.tracking.mapper:
- config.vast:
- container:
- Methods
- load(uri:
String) =>Promise: Fetches a VAST ad tag and loads one of its<MediaFile>s into the container. The returnedPromisewill be resolved when it is safe to start playback viastartAd(). - startAd() =>
Promise: Starts playback of the ad. This method may only be called once. The returnedPromisewill be fulfilled when the ad starts playing. This method cannot be called until thePromisereturned byload()is fulfilled. - stopAd() =>
Promise: Stops playback of the ad and cleans-up its resources. Once this method has been called, the ad cannot be started again viastartAd(). The returnedPromisewill be fulfilled when the ad's resources are cleaned-up. This method cannot be called until thePromisereturned byload()is fulfilled. - pauseAd() =>
Promise: Pauses ad playback. The returnedPromisewill be fulfilled when the ad pauses. This method cannot be called until thePromisereturned bystartAd()is fulfilled. - resumeAd() =>
Promise: Resumes ad playback. The returnedPromisewill be fulfilled when ad playback resumes. This method cannot be called until thePromisereturned bypauseAd()is fulfilled.
- load(uri:
- Properties
- container:
Node: The supplied container. - config:
Object: The supplied configuration, with defaults applied. - vast:
VAST: A vastacularVASTinstance representing the fetched ad tag. - ready:
Boolean: Indicates if the ad is ready for playback. - adRemainingTime:
Number: The amount of time (in seconds) left in the linear ad. Accessing this property before the ad is loaded will throw anError. - adDuration:
Number: The total duration of the ad (in seconds.) Accessing this property before the ad is loaded will throw anError. - adVolume:
Number: Gets/sets the volume of the ad with0being completely silent and1being as loud as possible. Accessing (or setting) this property before the ad is loaded will throw anError.
- container:
- Events: All VPAID 2.0 events are supported. A subset of these events are supported for non-VPAID
<MediaFile>s as well. In addition, the following events are emitted:- ready: Fired when
startAd()may be called and thereadyproperty becomestrue. - error: Fired when an error occurs with ad loading/playback.
- ready: Fired when
VASTPlayer.vpaidSWFLocation:String
The location of the SWF needed for Flash VPAID playback. The defaults to a location on the jsDelivr CDN. Only override this property if you want to use a version of the SWF you have uploaded yourself.