Advertising with the FreeWheel Plugin

Overview

This plugin enables FreeWheel ad technology in the Brightcove Player.

Testing the ad server

The first thing you should do is verify the validity of the ad tag you are planning to use. Be sure you have copied its URL and browse to the following page: Ad Previewer (clicking this link will cause the page to open in a new window or tab).

Paste your ad tag URL into the indicated form input field. Click OPEN IN AD PREVIEWER. A popup titled Open In Ad Previewer will display, and you then click the OPEN button to test your ad. Click PLAY and, if functioning correctly, your ad will display interspersed with a video. If your ad tag is not working in this test environment, it will not work with Brightcove Player.

Consent/GDPR support

The default AdManager SDK is v7.2.0 This supports Consent Management Platforms (CMPs) implementing the TCF v2 framework out of the box, with no plugin configuration required. CMPs implementing TCF v1 are no longer supported. More information in Freewheel's documentation (Freewheel Hub login required)

Steps

1. Include the link to the CMP script in the page where the player is embedded

   Example

   <script src="//your_cmp_address.net/cmp/cmp.complete.bundle.js" async></script>

2. Make sure you are using version 7.2.0+ of the Freewheel SDK. This is the default version if the sdkUrl option is not used. If you wish to set a version with either sdkUrl or sdkVersion, ensure the version is set to 7.2.0 or newer.

Implement using Players module

Players module support will be available soon.

Implement with JSON Editor

In the Players module, navigate to the player you want to configure and click the link for the JSON Editor. Modify the "plugins" array to add the FreeWheel plugin.

      
        "plugins": [
        {
          "name": "freewheel",
          "is_packaged": true,
          "options": {
            ...
          }
        }
      ]
    
    

Configuration

The following settings are used to configure the FreeWheel plugin:

Ad Slot Configuration

Temporal Slots

Temporal slots define when and where ads should play during video playback. Configure them using the temporalSlots array:

      {
          "temporalSlots": [
              {
                  "customId": "preroll",
                  "adUnit": "preroll",
                  "timeposition": 0
              }
          ]
      }

Temporal Slot Properties

Ad macros

There are ad macros available to make your job easier when configuring FreeWheel. The ad macros are replaced with corresponding values anywhere in your configuration.

The following is the complete list of variable for which substituted values will be used:

cust_params={mediainfo.ad_keys}

Example configuration

"plugins": [{
  "name": "freewheel",
  "is_packaged": true,
  "options": {
      "keyValues": [{
        "feature": "simpleAds",
        "module": "DemoPlayer"
      }, {
        "feature": "trackingURLs"
      }],
      "networkId": 99999,
      "profile": "global-js",
      "serverUrl": "https://cue.v.fwmrm.net/ad/h/5",
      "siteSectionCustomId": "your value here",
      "temporalSlots": [{
        "adUnit": "preroll",
        "customId": "Preroll_1",
        "timePosition": 0
      }, {
        "adUnit": "postroll",
        "customId": "Postroll_1",
        "timePosition": 60
      }, {
        "adUnit": "overlay",
        "customIdd": "Overlay_1",
        "timePosition": 5
      }],
      "videoAssetCustomId": "your value here",
      "videoAssetDuration": 500
    },
    "debug": true,
    "prerollTimeout": 1000,
    "timeout": 5000
}]

Events

The plugin emits some custom event types during loading, initialization, and playback. You can listen for the ad framework events just like you would any other event:

player.on('ads-ad-started', function(event) {
  console.log('event', event);
});

Dynamic server URL assignment

You can use the fw-before-ad-request event to dynamically assign the server URL. You will use the on() method to listen for the ad request, then assign the desired server URL. Of course, you will need to supply your desired server URLs for the placeholders in the code:

player.on('fw-before-ad-request', function () {
  player.setOptions({
    serverUrl: '[your server url]'
  })
})

If you have configured the server URLs previously, the code shown will override the previous configuration.

Player Ad Libraries

The videojs/videojs-contrib-ads GitHub repository contains a plugin which provides common functionality needed by video advertisement libraries working with Brightcove Player. The plugin provides common functionality needed by video ad integrations and takes care of a number of concerns for ad integrators, reducing the code you have to write for your ad integration.

Properties

videojs-contrib-ads provides some properties that can be helpful. They are:

The following code demonstrates the use of the properties:

myPlayer.on('ads-ad-started',function( evt ){
  console.log('*****ads-ad-started event passed to event handler', evt);
  console.log('myPlayer.ads.ad.id',myPlayer.ads.ad.id);
  console.log('myPlayer.ads.ad.index',myPlayer.ads.ad.index);
  console.log('myPlayer.ads.ad.duration',myPlayer.ads.ad.duration);
  console.log('myPlayer.ads.ad.type',myPlayer.ads.ad.type);
  setTimeout(function(){
    console.log('****myPlayer.ads.ad.currentTime()',myPlayer.ads.ad.currentTime());
  },500);
  setTimeout(function(){
    console.log('****myPlayer.ads.ad.currentTime()',myPlayer.ads.ad.currentTime());
  },1000);
});

The output in the console from the above code is shown here:

Methods

videojs-contrib-ads provides some methods that can be helpful. They are:

Known issues

Dynamically re-using the same player with FreeWheel

If you are loading videos dynamically and re-using the same player, the FreeWheel configuration settings will contain the same values as they were set at the time the FreeWheel plugin was instantiated, unless setOptions() is used to update the settings.

Resizing player during ad playback

If the player is resized during ad or video playback, ad content will not resize unless the player's dimensions function is called to resize the player. Resizing the player using other methods (for example: style width and height) will not resize the ad.

When using player.dimensions(width,height) to resize the player, you will have to trigger the fw-resizeplayer event so that the plugin will know the dimensions have changed. This is because some VPAID ads retain the default dimensions of the ad and will not automatically resize when the player resizes.

Here is an example:

player.dimensions(960,540);
player.trigger('fw-resizeplayer');