A Video.js (legacy) plugin for playing VAST and VPAID ads.
Initially based on videojs-vast-plugin, it has been substantially rewritten for Video.js 8 and kept up to date with its dependencies.
npm install @muppy/videojsx-vast-plugin video.js videojs-contrib-adsvideo.js and videojs-contrib-ads are peer dependencies — they are required at runtime and are not bundled in the module builds.
There are 3 ways to use this: import the module to create your own player or plugin, or simply use the plugin script or the all-in-one player script.
To be used by your chosen bundler or build tool.
Like videojs-contrib-ads, importing the plugin as a side effect — it registers itself automatically on the videojs instance:
import videojs from 'video.js';
import 'videojs-contrib-ads';
import '@muppy/videojsx-vast-plugin';
import 'video.js/dist/video-js.css';
import '@muppy/videojsx-vast-plugin/style.css';
// ... export something or get straight to it, you know the drill.
const player = videojs('vid1');
player.vast({ url: 'https://your-vast-url.com/vast.xml', skip: 8 });CommonJS works the same way — the require call registers the plugin as a side effect:
require('videojs-contrib-ads');
require('@muppy/videojsx-vast-plugin');Host the files ./dist/videojsx.vast.css and ./dist/videojsx.vast.js somewhere. The CSS is optional - you may want to apply different styling.
Remember to also add the dependencies on the page: Video.js and videojs-contrib-ads. Load ordering does matter. Be sure you request Video.js first and videojs-contrib-ads anywhere before videojsx.vast.js.
It will look something like this:
<head>
<!-- video.js framework -->
<link href="https://cdnjs.cloudflare.com/ajax/libs/video.js/8.23.9/video-js.min.css" rel="stylesheet">
<script src="https://cdnjs.cloudflare.com/ajax/libs/video.js/8.23.9/video.min.js"></script>
<!-- Ads plugin for video.js -->
<link href="https://cdnjs.cloudflare.com/ajax/libs/videojs-contrib-ads/7.3.2/videojs.ads.css" rel="stylesheet">
<script src="https://cdnjs.cloudflare.com/ajax/libs/videojs-contrib-ads/7.3.2/videojs.ads.min.js"></script>
<!-- This plugin for video.js -->
<link href="http://where-you-host-the-plugin.com/videojsx.vast.css" rel="stylesheet">
<script src="http://where-you-host-the-plugin.com/videojsx.vast.js"></script>
</head>A great way to get started quickly.
Take the ./dist/player.js file and host it somewhere.
player.js bundles Video.js, videojs-contrib-ads, and all CSS into a single file — nothing else is needed:
<head>
<script src="https://where-you-host-the-plugin.com/player.js"></script>
</head>Simple example:
<video id="vid1" width="640" height="400" controls class="video-js vjs-default-skin" data-setup='{"autoplay":false}' poster="optional-poster.jpg">
<source id ="mysrc" src="your-content.mp4" type="video/mp4">
Your browser does not support video.
</video>
<div id="companion"></div>
<script>
var player = videojs("vid1");
var companion = {
elementId: "companion",
maxWidth: 300,
maxHeight: 250
};
player.vast({url: "https://your-vast-url.com/vast.xml", skip: 8, companion: companion});
</script>There are many ways to integrate the player onto the page. For example, dynamically adding the elements via JavaScript.
In all cases, be sure player.vast({...}) is called immediately after Video.js in the same "tick".
Otherwise, the videojs-contrib-ads, a dependency of this plugin, may error on every page load or occasionally — depends on your integration. If there was a problem, no ad will play, and you'll see this message in the console:
videojs-contrib-ads has not seen a loadstart event 5 seconds after being initialized, but a source is present. This indicates that videojs-contrib-ads was initialized too late. It must be initialized immediately after video.js in the same tick. As a result, some ads will not play and some media events will be incorrect.
For more information, see https://videojs.github.io/videojs-contrib-ads/integrator/getting-started.html#important-note-about-initialization
If you want to initialize later, simply delay setting the video player's source. Once the source is set, then immediately call player.vast({...}). Calling player.vast({...}) before setting the source also works.
| Name | Optional | Default | Description |
|---|---|---|---|
url |
Yes | n/a | URL that responds with a VAST XML ad tag. Can be an array of URLs to be used as fallbacks (Ad Waterfall) - if the first URL fails to get ads, then the next URL will be tried, and so on until a VAST with ads is found. |
xml |
Yes | n/a | The VAST XML ad tag. Use as an alternative to url. Can be a String or XMLDocument. |
seekEnabled |
Yes | false |
Enable the player seek control when advert is playing. controlsEnabled must be enabled also. |
controlsEnabled |
Yes | false |
Enable the player controls (pause, play, volume) when advert is playing |
wrapperLimit |
Yes | 10 |
Maximum number of VAST wrappers (aka VAST request redirects) allowed |
withCredentials |
Yes | true |
Enable third-party cookies on the VAST request |
skip |
Yes | 0 |
Number of seconds the user has to wait before the advert can be skipped |
honorSkipOffset |
Yes | false |
Honor the VAST creative's skipoffset attribute if it is present; in that case, the skip option will be ignored. |
displayRemainingTime |
Yes | false |
Display the remaining time until the ad ends |
displayRemainingTimeIcons |
Yes | false |
Display play/pause and mute/unmute icons before the remaining time message |
messages |
Yes | {} |
See Messages options below |
companion |
Yes | {} |
See Companion options below |
vpaid |
Yes | {} |
See VPAID options below |
schedule |
Yes | n/a | An array of schedule items. If provided, the url and xml properties of this object will be ignored |
| Name | Optional | Default | Description |
|---|---|---|---|
skip |
Yes | Skip |
Message displayed on the clickeable button to skip the ad |
skipCountdown |
Yes | Skip in {seconds}... |
Message displayed for the countdown to enable skip of the ad. {seconds} will be replaced with the number of seconds left to skip the ad |
remainingTime |
Yes | This ad will end in {seconds} |
Message displayed for the countdown to the end of the ad. {seconds} will be replaced with the number of seconds left to the end of the ad. Displayed only if displayRemainingTime is enabled |
| Name | Optional | Default | Description |
|---|---|---|---|
elementId |
Yes | null |
Id of the HTML element that will serve as the creative container |
maxWidth |
Yes | 0 |
The maximum width allowed for the creative |
maxHeight |
Yes | 0 |
The maximum height allowed for the creative |
| Name | Optional | Default | Description |
|---|---|---|---|
videoInstance |
Yes | 'same' |
Determines which video element to pass to the VPAID ad. Either 'none' or 'same'. |
containerClass |
Yes | 'vjs-vpaid-container' |
The class name of the container that will house the VPAID iframe. |
enableToggleMute |
Yes | false |
Show a transparent icon button on the video (bottom-right) that the user can use to mute and unmute the audio. |
| Name | Optional | Default | Description |
|---|---|---|---|
url |
Yes | n/a | Same as the url option on the top level |
xml |
Yes | n/a | Same as the xml option on the top level |
offset |
Yes | 'pre' |
When to play the ad tag. See possible values below. |
Offset values:
pre: (string) Play before the content (preroll).post: (string) Play after the content (postroll).- number: (number or string) Play after the specified number of seconds. For example,
15. - xx%: (string) Play after xx% of the content. For example,
75% - time code: (string) Play at a specific time, in HH:MM:SS or HH:MM format. Examples:
1:30:12(1 hour, 30 mins, 12 secs),2:00(2 hours),0:25(25 mins).
Clone the project from Github. The source and build scripts are not published to the npm repository.
This project uses LFS for versioning large files (e.g., mp4). Only useful for development. Please see Git Large File Storage on Github for details.
Example setup for Mac OS:
brew install git-lfs
git lfs installIf you already cloned this repo before installing LFS and want to get the real content (replace pointer files):
git lfs checkout
git lfs fetchNodeJs and its package manager (npm) is required to build.
Run npm install then npm run build.
The build creates the following files in the dist/ folder:
| Artifact Name | Files | Description |
|---|---|---|
| Plugin Script | videojsx.vast.js, videojsx.vast.js.gz, videojsx.vast.css | Standalone plugin that can be integrated to an external video.js player. |
| Video Player Script | player.js, player.js.gz | A file that has video.js, css and other dependencies bundled in. |
| ES Module | videojsx.vast.es.js, videojsx.vast.es.js.map | For build tools that support ES6 Modules (ESM) |
| CommonJS Module | videojsx.vast.cjs.js, videojsx.vast.cjs.js.map | For build tools that support CommonJS Modules |
Run npm start brings up a development server at port 9999 with automatic background builds.
The page is http://localhost:9999/index.html
The command should automatically open this page.
The build will be triggered when any of the files under src/ is modified. The currently opened page on port 9999 should reload automatically.
Is currently in an experimental state.
- This plugin is a modification of an existing plugin videojs-vast-plugin by The Onion
- The Video.js Framework itself
- Video.js's Ad plugin allowing video ad integration (switching between content and pre-roll)
- Dailymotion's VAST client to parse and read VAST content
- MailOnline's VPAIDHTMLClient. A JavaScript iframe wrapper for VPAID