Guide: Ad Partner Integration

Overview

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:

Learning Guide: Video Advertising

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/videojs.ads.css">
<script src="//mypath/videojs.ads.js"></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
    myPlayer.ads();
  });
</script>

Note: While the ready() method is used to indicate that the player is loaded and ready, the loadedmetadata event is used to indicate that the player content, like ads, is ready to interact with. Here, we are also using the one() method so that our function is executed the first time the plugin is loaded and not every time a video is loaded. For details, see the Player Events document.

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
    myPlayer.ads({
      "timeout": 3000
    });
  });
</script>

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

Events

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.

Example

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

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

<head>
  <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>
</head>

<body>

  <video-js id="myPlayerID"
    data-account="1752604059001"
    data-player="default"
    data-embed="default"
    controls=""
    data-video-id="6077029038001"
    data-playlist-id=""
    data-application-id=""
    width="960" height="540"></video-js>

  <script src="https://players.brightcove.net/1752604059001/default_default/index.min.js"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/videojs-contrib-ads/6.9.0/videojs.ads.js"></script>

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

    player.ads();

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

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

    // can fetch ad inventory here...
    player.setTimeout(() => {
      creative = 'https://solutions.brightcove.com/bcls/ads/bc-ads/bcls-ad-1-8seconds.mp4';
    }, 100);
    player.trigger('adsready');

    // 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");

      player.ads.startLinearAdMode();
      // play your linear ad content
      player.src(creative);
      player.one('durationchange', function () {
        player.play();
      });
      // when ad has finished restore player
      player.one('adended', function () {

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

        player.ads.endLinearAdMode();
      });
    });

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

</html>

FAQ

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.