Guide: Ad Partner Integration

This document describes functionality you can implement if you wish to integrate your advertising system with Brightcove Player.


If your advertising system is compliant with Google IMA3, for instance, you do not need this information but can simply use the existing plugin for IMA3, documented in the Advertising with IMA3 Plugin Guide.

If you have determined you need this functionality, this content explains the advertising API framework needed for advertising integrations with the Brightcove Player. You can see two implementations of this framework that Brightcove has produced, those being for Google's IMA3 and FreeWheel (reference documents shown in the next paragraph).

Again, this document is NOT intended for customers wanting to use an existing ad framework with their videos. Documents more suitable for these customers are:

Ad framework functionality

Brightcove provides an advertising API framework as the basis for custom ad plugins. The framework provides common functionality needed by video advertisement libraries working with the Brightcove Player, reducing the code you have to write for your ad integration. The framework is provided as an open source project upon which you can build. The project code is available from the GitHub repository videojs-contrib-ads.

The ad framework enables ad partners to:

  • Have complete control over the advertising experience (i.e., the look and behavior of the player while ads are playing).
  • Work with custom or proprietary ad servers.
  • Manage low-level ad implementation details, like determining when ad requests are made and how creatives are buffered.
  • Easily interoperate with video analytics providers and the Brightcove Player ecosystem.

Base knowledge

To use and build upon the advertising API framework you will need a thorough understanding of Brightcove Player plugin architecture. The following documents provide this knowledge:

If necessary for you, a quick overview of video advertising from Brightcove's perspective can be found here:

Using the framework

The following sections provide details on using the framework.

Include the framework resources

To use the plugin you must first be sure to include the CSS and JavaScript for the plugin.

<link rel="stylesheet" href="//mypath/">
<script src="//mypath/"></script>

Once the JavaScript is included you can then call the function to initialize the ad framework.

<script type="text/javascript">
  videojs.getPlayer('myPlayerID').one('loadedmetadata', function(){
    var myPlayer = this;
    // Initialize the ad framework;

Configuration options

There are a number of configuration options available for the framework. For instance, there is a timeout option. To set this option you would use the following code:

<script type="text/javascript">
  videojs.getPlayer('myPlayerID').one('loadedmetadata', function(){
    var myPlayer = this;
    // Initialize the ad framework{
      "timeout": 3000

This table provides a list of the options:

Option Type Default Description
timeout number 5000 The maximum amount of time to wait for an ad implementation to initialize before playback, in milliseconds
prerollTimeout number 1000 The maximum amount of time to wait for an ad implementation to initiate a preroll, in milliseconds
postrollTimeout number 100 The maximum amount of time to wait for an ad implementation to initiate a postroll, in milliseconds
debug boolean false If debug is set to true, the ads plugin will output additional information about its current state during playback


The following events are grouped into two different types. The groupings and their descriptions follow.

The adstart and adend events are triggered by the framework in response to method calls from the ad integrator. These events should not be triggered by the ad integrator directly.

Event Description
adstart The player has entered linear ad playback mode
adend The player has returned from linear ad playback mode

The adskip and adtimeout events are optional events that the ad integrator can choose trigger to indicate the player should skip a preroll or postroll opportunity.

Event Description
adskip The player is skipping a linear ad opportunity and content-playback should resume immediately
adtimeout A timeout managed by the plugin has expired and regular video content has begun to play

Runtime settings

Once the plugin is initialized, there is a property you can use to modify its behavior.

Property Description
contentSrc This property is used to determine when a new video loads so that the player can be reset to the "get ready to show a preroll" state. Ad providers would not typically interact with it, but a plugin author who wished to change the video source to implement a rendition selector, for instance, could modify the contentSrc so that a preroll wasn't initiated when a rendition switch occurred.


This section provides an example of an implementation with a full working sample.

<!DOCTYPE html>
<html lang="en">

  <meta charset="UTF-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Contrib ads ad plugin</title>


  <video-js id="myPlayerID"
    width="960" height="540"></video-js>

  <script src=""></script>
  <script src=""></script>

    const player = videojs.getPlayer("myPlayerID");
    let creative = '';;

    player.on('contentupdate', function () {

    // Console output
    console.log("### videojs EVENT: contentupdate");

    // can fetch ad inventory here...
    player.setTimeout(() => {
      creative = '';
    }, 100);

    // Console output
    console.log("### videojs EVENT: adsready");


    player.on('loadedmetadata', function () {
    // Console output
    console.log("### videojs EVENT: loadedmetadata");

    player.on('readyforpreroll', function () {

      // Console output
      console.log("### videojs EVENT: readyforpreroll");;
      // play your linear ad content
      player.src(creative);'durationchange', function () {;
      // when ad has finished restore player'adended', function () {

        // Console output
        console.log("### videojs EVENT: adended");;

    player.on('ended', function () {
      // Console output
      console.log("### videojs EVENT: ended");



How can an ad plugin access media metadata? For Video Cloud customers, the plugin will access metadata via the mediainfo object, which will be populated with metadata set in Video Cloud. Brightcove Player customers will be responsible for populating the mediainfo object manually since they'll be using a non-Video Cloud CMS.
How can options be specified for an ad plugin? Plugin options can be specified in Studio's Players > Plugins section. The player with the plugin containing options can be published using an iframe or in-page embed code, but the plugin options contain static info (e.g., description). You can pass dynamic data to the plugin using the technique shown in the Pass Data to the Plugin document.
How should an ad plugin support Flash-based ads? Brightcove recommends packaging a Flash-based ad player as part of your ad plugin implementation and overlaying that player over the content while the player is in linear ad mode.
How can cue points trigger mid-rolls? On cue change, call startLinearAdMode() to begin the midroll. For information on listening for, and setting, cue points see the Using Cue Points document.