@video-js/ad-schedule-plugin

VideoJS VAST Plugin

The goal of this plugin is to allow videojs consumers to display VAST-based or VMAP-based ads with the very same video element created by VideoJS.

Contrary to the commonly used Google IMA for VideoJS, this plugin is not opinionated regarding the UI - i.e. it leaves to the consumer to manage changes in the UI to satisfy user needs.

This plugin is based on video-contrib-ads to provide common functionality needed by video advertisement libraries like this very plugin. It is also based on Daily Motion's VAST Client JS for fetching and parsing VAST XML resources as well as managing the tracking protocols described in the VAST documentation by Interactive Advertising Bureau (IAB). The plugin was tested with VAST manifests of versions 3.0 and newer, but should work with older versions as well.

Benefits

• Full control over the player UI while playing an ad
• Ad is played inline in the same video element as the regular video which avoid visual and auditory glitches
• Full support for basic ad types described by the VAST protocol as well satellite features like tracking and verification code
• Ad timeouts are implemented by default. If ads take too long to load, content automatically plays.
• Player state is automatically restored after ad playback, even if the ad played back in the content's video element.
• Schdeule Ad Break as a midroll
• This Plugin Supports Preroll, Midroll, Postroll Ad breaks in HTML5 Based Smart TV, Like Tizen, WebOS, VIZIO TV, XBOX, Zeasn etc.

Table of contents

• Getting Started
• Implementing a CTA
• Options
• Events
• Runnning locally
• Credits
• License

Getting Started

In order to start using the VAST Plugin you are supposed to have started a project that consumes VideosJS and have some basic knowledge of its basic concepts and API. To get started, install and include this package in your project's dependencies using npm or yarn:

npm install --save @video-js/ad-schedule-plugin
yarn add @video-js/ad-schedule-plugin

Now, import the plugin package and initialize it right after initializing your VideoJS instance. Here's a small snipet that of what it could look like:

// Import the necessary packages
import videojs from 'video.js';
import '@video-js/ad-schedule-plugin';

// Create VideoJS instance
const videoJsInstance = videojs('my-player', {
  controls: true,
  autoplay: false,
  preload: 'auto'
});

// Set up the VAST options
// `Supported Options = vastUrl || vmapUrl || adUrl || verificationTimeout || addCtaClickZone || addSkipButton || debug || timeout || isLimitedTracking`

const adsOptions = {
  adUrl: 'https://points-to-vast-manifest.com/',
};

// Initialize the VAST plugin
videoJsInstance.vast(adsOptions);

// Do something with Ads events
videojsInstance.on('vast.play', (event, data) => {
    console.log('Ad is playing');
});

If you want to schdeule the Ad again as a midroll.
//videoJsInstance.vast().scheduleAdBreak(adsOptions);

Implementing a CTA

The "vast.play" event contains data letting you handle cta clickzone as you want

{
  ctaUrl // the url the click should point to
  skipDelay // the time in seconds the skip button should be displayed
  adClickCallback // call this callback on click on your optional clickzone
}

By default the plugin handle the cta clickzone. You can disable this default behavior by setting the "addCtaClickZone" to false

Options

This plugin currently supports a handful of options that might help you customize it to your needs. Below you can find a description of the options supported to this date. Please bear in mind this is a work in progress and more options should be available in the future, especially if requested through this repository.

• vastUrl (string) - The URL where the plugin will fetch the VAST manifest from
• vmapUrl (string) - The URL where the plugin will fetch the VMAP manifest from
• adUrl (string) - The URL where the plugin will automatically detect and play VMAP or VAST manifest Ad
• isLimitedTracking (boolean) - According to the Vast documentation, relates to the LIMITADTRACKING macro. Default : false
• timeout (milliseconds - int) - Max amount of time the plugin should wait for the manifest URL to respond and the assets to load. Will throw an error if this value is exceeded. Default: 5000
• verificationTimeout (milliseconds - int) - Max amount of time the plugin should wait for the OMID verification URLs to respond and the assets to load. Default: 2000
• debug (boolean) - Display detailed logging in the browser console. Default: false
• addCtaClickZone (boolean) - Add or not a clickzone for the cta url. Default: true
• addSkipButton (boolean) - Add or not a skip button for skippable ads. Default: true

Events

The plugin communicates with the consumer through default event bus built into VideoJS. Here's an example of how one could attach a listener to a vast event using the VideoJS' event bus:

// Do something when there is an ad time update
videojsInstance.on('vast.time', (event, data) => {
    console.log('Ad is playing');
    console.log('Current position - ' + data.position);
    console.log('Total Duration - ' + data.duration);
});

Below you can find a list of the events currently supported. Just like the plugin options, this is a work in progress and more events should be available in the future, especially if requested through this repository.

• vast.canplay - The plugin successfully parsed the VAST manifest and is capable of playing an ad
• vast.playAttempt - The plugin will try and play a creative of an ad. It might be the case that the creative fails to load, in which case vast.play will never be fired
• vast.play - The plugin started playing a creative
• vast.time - Called every 100ms or so, this event gives the consumer an update of the current position within a creative
• vast.complete - Called once the current ad pod (set of ads) is done playing
• vast.error - Called if the plugin fails at some point in the process
• vast.click - Called once the plugin succeffully registers a click in the call to action element associated with an ad - check the Implementing a CTA section for more details

Additional Available Events: adplaying | adpause | adtimeupdate | advolumechange | adfullscreen | adtimeout | adstart | aderror | readyforpreroll | readyforpostroll | skip | adended | ended |

Call player.ads.isAdPlaying() to check if ad is playing or not.

Runnning locally

Running the plugin locally to further develop it is quite simple. Since the plugin repository does not contain any self contained development environment, we recommend using yalc to publish the package in a local repository and then use yalc again to install the plugin from the same local repository in in a dedicated development environment or even within the project you are working on.

Here's a small step-by-step to run the plugin locally.

• Install Yalc globally with npm i yalc -g or, using yarn: yarn global add yalc
• Clone the repository with git clone https://github.com/aviral-zype/videojs-vast-plugins.git
• Install the plugin dependencies with npm install
• Run the plugin in watch mode with npm start, leave this terminal open while you are working on the plugin's code
• In your local project, run yalc add @video-js/ad-schedule-plugin to install the plugin from your local repository
• Run your project normally, it will consume the local version of the plugin

Credits

Current contributors and maintainers: @aviral-zype

License

This plugin, just like Video.js, is licensed under the Apache License, Version 2.0.