On This Page

Implementing Server-Side Ads with the Brightcove Player

In this topic, you will learn how to use Server-Side Ad Insertion (SSAI) with the Brightcove Player to deliver ads stitched into your video streams.

Overview

Server-Side Ad Insertion (SSAI) allows you to embed ads into your videos so that they can't be blocked by ad blockers in the browser. Dynamic Delivery is the next generation ingest and delivery system which reduces your storage footprint and dynamically packages media.

By default, SSAI enforces that all advertisements are watched, displaying an ad count-down timer while they play. You can easily customize this feature to skip advertisements.

You can configure the Brightcove Player to use client-side ads when they are not blocked and automatically failover to SSAI when an adblocker is detected. For more information on how to enable this feature, see the Ad failover document.

Notes:

To use SSAI, your Video Cloud account needs to be configured for Dynamic Delivery and enabled for SSAI. Contact your account manager to start using this feature.

SSAI for live playback does not require the SSAI plugin, and client-side features for SSAI playback are not available for live. For details, see the Brightcove Live API with SSAI document.

Player example

This example uses IMA ads defined in a VMAP file to deliver server-side ads in the video stream. You should see that there is a pre-roll, mid-roll and post-roll ad. The VMAP file is defined in the ad configuration.

Create a Brightcove player

Implementing SSAI using Studio

The easiest way to configure your player for server-side ads is with Video Cloud Studio. Once you have created an ad configuration and player, then you are ready to configure the player for SSAI as follows:

Open the PLAYERS module and locate the player to which you want to add advertising functionality.

Select the link for the player to open the player's properties.

Select Advertising in the left navigation menu.

Check the Enable Server-Side (SSAI) checkbox.

From the Select Configuration dropdown menu, select the ad configuration that you would like to associate with this player.

If you want overlays to display over your ads, check the Enable ad information overlays checkbox. This includes "Learn More" and ad count down overlays.

The completed form should look similar to this:

SSAI advertising in Players module

Select Save.

To publish the player, select Publish & Embed > Publish Changes.

When the changes to the advertising properties are saved, the SSAI plugin will be configured as part of the Plugin settings. The JavaScript and CSS will be hidden since you added them via the Advertising section.

Play a video with ads

Any video that you retrieve from Video Cloud that has been ingested with Dynamic Delivery, will include the ads specified in the VMAP file in your ad configuration. Note that the video needs to have an audio track associated with it for SSAI to work.

Implementing SSAI programmatically

Once you have created an ad configuration and player, then you are ready to configure the player for SSAI follows:

Playing a video with ads

Any video that you retrieve from Video Cloud that has been ingested with Dynamic Delivery, will include the ads specified in the VMAP file in your ad configuration. Note that the video needs to have an audio track associated with it for SSAI to work.

Options

debug

If true, sets up debug messages in contrib-ads and logs extra information in the presence of videojs-bc-analytics-logger.

hideOverlays

If true, the countdown timer and Learn More click through overlays will not be shown while ads are playing.

trackingBeacons

If false, the tracking beacons parsed from the VMAP for ad view, impression, quartiles, etc. will not be sent.

timeout

The number of milliseconds after which an XHR to fetch a VMAP will time out.

Styling

There are several useful HTML classes applied to the player by this plugin that can be targeted to determine the plugin's state.

Class

Usage

vjs-ssai

Indicates that the SSAI plugin has been instantiated, but is not necessarily enabled. This will be present even when not playing an SSAI source.

vjs-ssai-enabled

The SSAI plugin is currently enabled. In other words, an SSAI source has been set on the player.

vjs-ssai-disabled

The SSAI plugin is not currently enabled.

vjs-ssai-waiting

The SSAI plugin is waiting for data or some other external process.

vjs-ssai-not-waiting

The SSAI plugin is not waiting for anything.

vjs-ssai-hide-overlays

The hideOverlays option has been set to true.

vjs-ssai-show-overlays

The showOverlays option is set to true. This is the default.

Events

At the current time there is one SSAI-specific event dispatched by this plugin. It is prefixed with bcov-ssai-.

bcov-ssai-click-through

This event is dispatched internally by the plugin to indicate that an ad click-through was requested.

Configuration notes

Preloading ads should not be done with SSAI. The reason for this is that if you preload the player will report an ad impression and probably the first quartile beacons before the video is played. This could lead to inaccurate ad analytics. If you configure SSAI in Studio, this will automatically be done, but if you happen to setup SSAI manually you need to be aware of this issue.

If the web player is using SSAI, and one of your motivations for doing so is to work around ad blockers, you should use server-side beacons. Client-side beacons should not be used as they will be blocked.

Glossary

This plugin distinguishes the concepts of absolute and content time within a Once UX stream. Traditional video players only have a concept of content time; times between start and end of the URI it is currently playing. Because a Once UX stream is essentially a number of content streams stitched together we've introduced the concept of absolute time which takes into account the complete stitched stream including the video advertisements.

When you see the prefix absolute on a property or method, the times expected/returned are relative to the entire stitched stream. When you see the prefix content, the times expected/returned are relative only to a particular piece of content that was stitched into the stream (the main content or single linear advertisement).

Absolute time : Refers to any given point in the total timeline of an SSAI stream. For example, a 2:00 video with a 0:30 pre-roll ad has a total absolute time of 2:30. The absolute time of 0:15 is in the pre-roll and the absolute time of 0:31 is the first second of content.

Relative time : Refers to the time relative to the current block of media - either content or ad. Expanding on the above, during the pre-roll, the relative time 0:15 is synonymous with the absolute time of 0:15, but the absolute time 0:31 would equate to a relative time of 0:01.

Generally, relative time is what you see in the player UI and much of the job of this plugin and associated middleware is translating from absolute time to relative time.

Known issues

Here are the known issues for using the SSAI plugin:

Safari 10/11 sometimes show the last frame of the postroll at the end of the video.

SSAI won’t stitch overlay ads into the video stream.

Changelog

17 Jan 2019

v1.4.3

Bug fix: When discontinuities are enabled, include the rule=discos-enabled parameter in the VMAP request

24 Oct 2018

v1.4.2

Bug fix: Do not fire playing event before a preroll

15 Oct 2018

v1.4.1

Bug fix: Selectively enable multiperiod for non-MS browsers

Bug fix: Video corruption in IE/Edge

9 Oct 2018

v1.4.0

Added option to request content with discontinuities

19 Sep 2018

v1.3.2

Updated videojs-contrib-ads to 6.6.1

12 Sep 2018

v1.3.1

Updated the plugin to use videojs-contrib-ads 6 and validate contrib-ads version on initialization

12 Sep 2018

v1.3.0

New feature: Display skip ad countdown overlay for skippable ads

Bug fix: Ad countdown stops when it reaches first quartile

Bug fix: Limit buffering UI to the current play window

Bug fix: Remove the postinstall script to prevent install issues

Updated using plugin generator v7.2.1

30 Jul 2018

v1.2.4

Fix: Handle ended as a special timeline case

Added an NVMRC

5 July 2018

v1.2.3

Bug fix: Ignore captions provided by VMAP

Test: Use vhs instead of videojs-contrib-hls

23 Mar 2018

v1.2.2

Send the BCOV-Once-Accept header for sources that come from once.unicornmedia.com