Upgrading to IMA3 Plugin Version 3

Overview

In May of 2018 Brightcove released version 3 of the IMA Advertising plugin. The update includes many major improvements in reliability, and other areas, which are detailed in the next section of this document. The update is for Brightcove Player version 6 and higher only. Existing version 6 players will not be migrated to version 3 automatically as some integrations may need to be updated to support the new version. Brightcove encourages you to read this document fully and then test the changes before upgrading.

Improvements

The following is a list of improvements made in version 3 of the plugin:

• The plugin’s handling of video source changes has been fundamentally reworked, resulting in far greater reliability when used with playlists.
• Setting the server URL can now be delayed, allowing for easy integration of asynchronous workflows such as header bidding or macros based on media info. The following are two examples:
  • The Jump Start: Header Bidding Ad document.
  • The Implement using code section of the IMA3 plugin document.
• A bug has been fixed that could have led to a longer timeout than expected.
• Flash support has been removed for improved performance.
• Various additional bug fixes and reliability improvements are rolled into the new version.

• You can give ad macros default values. A default value can be provided within a macro, in which case this value will be used where a variable is undefined. The syntax is:

  {macro=default}

  For instance,

  http://example.com/ad/{pageVariable.adConf=1234}

  would resolve to the following if window.adConf is undefined:

  http://example.com/ad/1234

Technical details

To improve reliability, the Brightcove IMA plugin has updated its dependency on videojs-contrib-ads, the open source Video.js ad framework, to version 6. This is a major maintenance update. You can learn more about videojs-contrib-ads version 6 on the Video.js blog.

This update removes a root cause of some content flashes that appeared before prerolls. The solution uses Video.js middleware to remove the need to do a quick play and pause at the beginning of playback.

Migrating to version 3

Existing players will NOT be automatically upgraded to version 3 of the Brightcove IMA plugin. In the default (legacy) Studio interface, version 2 of the IMA plugin will always be used, as it has in the past. In the beta (new) Studio interface, the Advertising section has a dropdown to allow you to pick which version of the IMA Plugin to use. This new interface can be used to migrate players. Brightcove strongly recommends reviewing your integration and carefully testing your player when upgrading.

Newly created players will use version 3 by default when advertising is enabled. They can be manually set to version 2 if needed.

Following is a list of changes that may require integrations to be updated:

• You may want to test to make sure you were not depending on a timeout longer than what is specified in your configuration.
• The ended events are no longer delayed by one second. If your integration responds to ended events, you should test that the integration continues to work as expected. Generally, this means that such integrations will perform better.
• The player.ads.state property is now deprecated. Brightcove has seen it used in some integrations to check if the player is in ad mode, but it is generally done incorrectly. A better alternative is to use the player.ads.isInAdMode() method.
• The contentplayback event has been removed. It is an implementation detail that is no longer needed, but we have found that some integrations use it. Use the playing event instead.
• Beginning of ad playback is indicated by the ads-ad-started event, which fires exactly once when each ad begins. While the adplaying event will continue to be emitted, it may now be emitted multiple times per ad play, so Brightcove therefore recommends using the ads-ad-started event instead.

Why a major version update?

Although the changes may seem modest, several key aspects of the interface have changed, prompting a major version update. Specifically, the elimination of the contentplayback event, as well as the specific behavior of the timeout parameter. While these may seem minor, some integrations may depend on their particular behavior. Since even small changes can make a big difference in some customer implementations, Brightcove feels a major version increment was appropriate to indicate integrations should be thoroughly tested before use in production.