Contact Support | System Status
Page Contents

    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.


    Sample implementation

    The hands-on exercise section of the Advertising with IMA3 Plugin Guide walks you through a simple implementation of using a plugin for IMA3 advertising.

    Pseudo code integration

    Here's pseudo code of what a basic ad integration might look like. This example shows a single preroll ad before each content video, and demonstrates the interaction points offered by the ads plugin. This is not actually a runnable example, as it needs more information as specified in the code comments.

    <script type="text/javascript">
      videojs.getPlayer('myPlayerID').one('loadedmetadata', function(){
        var player = this;; // initialize the ad framework
        // request ads whenever there's new video content
        player.on('contentupdate', function(){
          // fetch ad inventory asynchronously, then ...
        player.on('readyforpreroll', function() {
          // play your linear ad content
'durationchange', function(){
          // when all your linear ads have finished...
'ended', function() {


    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.

    Page last updated on 17 Jun 2021