Guide: Ad Partner Integration
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.
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
<link rel="stylesheet" href="//mypath/videojs.ads.css"> <script src="//mypath/videojs.ads.js"></script>
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:
This table provides a list of the options:
||number||5000||The maximum amount of time to wait for an ad implementation to initialize before playback, in milliseconds|
||number||1000||The maximum amount of time to wait for an ad implementation to initiate a preroll, in milliseconds|
||number||100||The maximum amount of time to wait for an ad implementation to initiate a postroll, in milliseconds|
||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.
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.
|adstart||The player has entered linear ad playback mode|
|adend||The player has returned from linear ad playback mode|
adtimeout events are optional events that the ad integrator can choose trigger to indicate the player should skip a preroll or postroll opportunity.
|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|
Once the plugin is initialized, there is a property you can use to modify its behavior.
|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
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.
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.