Integrator Docs | Developer Docs | Github

Getting Started


Install From NPM

npm install videojs-contrib-ads

Using a module bundler

This is the recommended approach. If you are including videojs-contrib-ads using a module bundler such as webpack, this example is a useful starting point:

With this basic structure in place, you’re ready to develop an ad plugin.

Including the files in your HTML

This is not the recommended approach, but may be useful in some cases. In addition to the video.js library, you’ll need two files from this project: and After you build the project they are both in the dist directory.

Include the CSS in your HTML’s <head> section with a <link> tag:

<link rel="stylesheet" href="">

Then, include the JavaScript file after video.js, but before your ad plugin code:

<video id="video" src="movie.mp4" controls></video>
<script src="video.js"></script>
<script src=""></script>
videojs('video', {}, function() {
  var player = this;; // initialize videojs-contrib-ads
  // your custom ad plugin code

You may also use the Javascript and CSS links from the following to get started:

Important Note About Initialization

In order to function correctly, videojs-contrib-ads must be initialized immediately after video.js (in the same tick). This is for two reasons:

The plugin will emit an error if it detects that it it missed a loadstart event. If this happens, it is likely that downstream failures will occur, so it’s important to resolve this issue.

Developing an Ad Plugin

First you call to initialize the plugin. Afterwards, the flow of interaction between your ad plugin and contrib-ads might look like this:

This is the basic flow for a simple use case, but there are other things the ad plugin can do. Refer to the API reference for more information.

Single Preroll Example

Here’s an outline of what a basic ad plugin might look like. It only plays a single preroll ad before each content video, but does demonstrate the interaction points offered by the ads plugin.; // initialize videojs-contrib-ads

// request ads whenever there's new video content
player.on('contentchanged', function() {
  // in a real plugin, you might fetch new ad inventory here

player.on('readyforpreroll', function() {;
  // play your linear ad content
  // in this example, we use a static mp4

  // send event when ad is playing to remove loading spinner'adplaying', function() {

  // resume content when all your linear ads have finished'adended', function() {;

// in a real plugin, you might fetch ad inventory here

To implement midroll ads, you might listen to timeupdate events to monitor the progress of the content video’s playback. To implement postroll ads, you’d listen to the readyforpostroll event.

For a more involved example that plays both prerolls and midrolls, see the examples directory in this project. For more detailed information about what events and methods are available, see the API reference.