On This Page

Advertising with the FreeWheel Plugin

In this topic, you will learn how to use the FreeWheel plugin to enable advertisements with video playback, and how it can be implemented using Studio and through custom coding.

Overview

This plugin enables FreeWheel ad technology, for either Flash or HTML5, in Brightcove Player. The default rendering option for the FreeWheel plugin is set to Html5 (for more information see the adTechOrder option below).

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, with two exceptions. The first exception is if you are using ad macros. The second exception is you can update the settings using player.FreeWheelPlugin.settings.Html5 or player.FreeWheelPlugin.settings.Flash on an fw-before-ad-request event.

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.

Implement using Players module

To implement the FreeWheel Plugin using the Players module, follow these steps:

Open the PLAYERS module and either create a new player or locate the player to which you wish to add the plugin.

The Options(JSON) provided in the form configure playback technology where Flash and Html5 configuration sections are provided by FreeWheel. A slightly altered (for security reasons) complete configuration is shown below . A stub example is shown here:

Implement using code

To implement a plugin the player needs to know the location of the plugin code, a stylesheet if needed, the plugin name and plugin configuration options. The location of the plugin code and stylesheet are as follows:

The name of the plugin is FreeWheelPlugin. The options configure playback technology where Flash and Html5 configuration sections are provided by FreeWheel. A slightly altered (for security reasons) complete configuration is shown below . A stub example is shown here:

Rendering options

The following table shows the Tech in which the FreeWheel plugin will render an ad (column 3) based on Tech selections in Brightcove Player (column 1) and the adTechOrder set in the plugin (column 2).

Brightcove Player
Selected Tech

FreeWheelPlugin adTechOrder

FreeWheel Plugin
Selected Ad Tech

html5

["flash","html5"]

flash

html5

["html5","flash"]

html5

html5

["html5"]

html5

html5

["flash"]

flash

flash

["flash","html5"]

flash

flash

["html5","flash"]

flash

flash

["html5"]

Not possible

flash

["flash"]

flash

Note: For the best user experience when delivering midrolls, you should use a segmented delivery format like HLS and deliver your content from a CDN that supports byte­range requests.

Configuration

The following settings are used to configure the Freewheel plugin:

adTechOrder:

Type: Array Default Value: ["html5"]

The array contains the ad integration technologies to attempt to use, in order of descending precedence.

Flash:

Type: Object

An object for Tech specific FreeWheel configuration (provided by FreeWheel). The object contains the following options:
These options can either be set dynamically (shown here) or as part of the initial configuration (shown here).

Optional values can be used based on FreeWheel Flash Plugin Version. Those values can be found in the Using versions of the plugin section near the top of this document.

Must be a child property of the Flash object. This will be directly applied to the object element if the Flash ad tech is used.

autoplay:

Type: boolean Default Value: true

Indicates if the content is autoplayed.

Must be a child property of the Flash object. This will be directly applied to the object element if the Flash ad tech is used.

unattendedPlay:

Type: boolean Default Value: false

When autoPlay is set to true, unattendedPlay indicates whether the user is aware of the autoplaying.

Must be a child property of the Flash object. This will be directly applied to the object element if the Flash ad tech is used.

visitorCustomId:

Type: string Default Value: unset

Allows publishers to pass a custom visitor id for the ad request. When set, this value will be passed in the visitor block of the request payload as customId="CustomID_001". The id will be returned in the response to the ad request in the opening visitor tag as an attribute: customId="CustomID_001".

Must be a child property of the Flash object. This will be directly applied to the object element if the Flash ad tech is used.

Html5:

Type: Object

An object for Tech specific FreeWheel configuration (provided by FreeWheel). The object contains the following options:
These options can either be set dynamically (shown here) or as part of the initial configuration (shown here).

autoPlayType:

Type: integer Default Value: 1

Indicates that the content video will autoPlay and the user is aware the content is autoplaying.

The values passed into autoPlayType sets flags in the ad request url sent to the Freewheel ad server and can be one of three integer values which equate to the related Freewheel SDK constants:

Must be a child property of the Html5 object. This will be directly applied to the object element if the Html5 ad tech is used.

visitorCustomId:

Type: string Default Value: (optional)

The visitorCustomId option allows publishers to pass a custom visitor id for the ad request. When set, this value will be passed in the ad request URL as the queryString vcid=CustomID_001. The id will be returned in response of the ad request in the visitor JSON block as "customId" : "CustomID_001".

Must be a child property of the Html5 object. This will be directly applied to the object element if the Html5 ad tech is used.

subsessionToken:

Type: int Default Value: (optional)

The subsessionToken option allows publishers to start a subsession with the given token. When set, this value will be passed in the ad request URL as the queryString:

ssto=1234567890

Must be a child property of the Html5 object. This will be directly applied to the object element if the Html5 ad tech is used.
Note: For the subsessionToken to function properly you must also include a capability in the ad request of [flag=+sync] as a parameter.

compatibleDimensions:

Type: array Default Value: (optional)

The compatibleDimensions option allows publishers to pass an array of compatible dimensions. For example:

If there is a temporalSlots option under the Flash or Html5 properties, the setting is ignored.

Note: When using cue point ads with the FreeWheel plugin, post-roll ads are not supported.

useMediaCuePoints:

Type: boolean Default Value: false

Must be set to true to use Video Cloud ad cue points to trigger ads. Must be used in conjunction with requestAdsMode: 'oncue' property and assigned value.

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:

Macro

Description

{player.id}

Player ID

{mediainfo.id}

Video ID

{mediainfo.name}

Video title

{mediainfo.description}

Short description (250 chars max)

{mediainfo.tags}

Tags (metadata) associated with the video

{mediainfo.reference_id}

Reference ID

{mediainfo.duration}

Duration of the video as reported by Video Cloud

{mediainfo.ad_keys}

Free form text string that can be added and edited in the Media module of Studio; you should use the query parameter in the form

cust_params={mediainfo.ad_keys}

{player.duration}

Duration of video as measured by player (possibly slightly different from mediainfo.duration and probably more accurate)

{document.referrer}

Referring page URL

{window.location.href}

Current page URL

{player.url}

URL of the player

{timestamp}

Current local time in milliseconds since 1/1/70

{random}

A random number 0-1 trillion

Note: If you are wishing to use the video ID as your FreeWheel videoAssetCustomId, you can do this using the {mediainfo.id} ad macro. For instance, in the configurations below you could do the following:

'videoAssetCustomId' = '{mediainfo.id}';

One FreeWheel configuration issue to be aware of: If the video ID is not configured as an Asset ID in the Freewheel Ad Manager configuration on the server, Freewheel will return an error of INVALID_ASSET_CUSTOM_ID.

Example configuration

Note: If you need to use HTTPS URLs in the configuration, substitute the following for those shown in the configurations in this doc:

The first ad in a linear ad pod (a sequenced group of ads) has started.

ads-pod-ended

The last ad in a linear ad pod (a sequenced group of ads) has finished.

ads-allpods-completed

All linear ads have finished playing.

fw-before-ad-request

This event is exposed on the player object and is triggered before submitting an ad request. Usually it is used in the context of playlists, to make updates to the FreeWheel Configuration settings via: player.FreeWheelPlugin.settings.Html5 or player.FreeWheelPlugin.settings.Flash

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:

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

Demos

The following demos use slightly different FreeWheel configurations and the resulting player. Both configurations will play a pre-roll, a mid-roll at 5 seconds and then a post-roll. The configurations are the same, except that the adtechOrder is different. In the first demo html5 is first, as shown here:

"adTechOrder": [
"html5",
"flash"
],

In the second the order is reversed.

adtech order: html5, flash

This demo uses html5 first in the adtechOder.

Following is the actual configuration used with the player. Note that this can be used for the options value in Studio.

Playlist

This demo uses the HTML first configuration with a playlist. You will see for each video in the playlist a pre-roll, a mid-roll at the 5 second mark, and a post-roll.

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:

Name

Data Type

Description

ads.ad.id

String

Unique identifier for an ad that plays

ads.ad.index

Number

The index of the ad that plays at a specified time; the index would identify the ordinal value of an ad in an ad pod

Methods

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

Method

Description

inAdBreak()

This method returns true during the time between startLinearAdMode and endLinearAdMode where an integration may play ads. This is part of ad mode.

isAdPlaying()

Deprecated

isContentResuming()

Returns true if content is resuming after an ad. This is part of ad mode.

isInAdMode()

Returns true if the player is in ad mode.

Known issues

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');

Overlay ads

If the FreeWheel plugin is rendering an ad in Flash, overlay ads are not clickable. If the FreeWheel plugin is rendering an ad in HTML5, overlays are not displayed at correct coordinates. Clicking on an HTML5 overlay ad will not pause the content player when the click-url is followed.