Advertising with the SSAI Plugin

Product(s)
Video Cloud
SSAI
Role(s)
Player Developer
Topic(s)
Advertising
SSAI

In this topic, you will learn how to use the Brightcove Player and the Server-Side Ad Insertion (SSAI) plugin to deliver ads stitched in to your video streams enabled for Dynamic Delivery.

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, the plugin enforces that all advertisements are watched and displays an ad count-down timer while they play. You can easily customize this plugin 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.

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.

See the Pen 18468-advertising-ssai-plugin by Brightcove Learning Services (@bcls1969) on CodePen.

View the source code.

Features

The SSAI plugin is a modern replacement for Once UX ad serving. The features include:

  • More complete VMAP/VAST parsing
  • Full support for VAST companion ads
  • New APIs for interacting with the timeline and linear ad rolls
  • Support for playlists, ad macros, and FairPlay
  • SSAI works with both DRM and non-DRM content.
  • One of the primary roles of this plugin is to enforce certain behaviors around seeking and ads.
  • Dual support for legacy Once UX VMAPs (using the uo namespace) and new Dynamic Delivery VMAPs (using the bc namespace)

Getting started

To play server-side ads from Video Cloud, you must first complete these steps:

  1. Create an ad configuration
  2. Create a Brightcove player

Once you have done this, you are ready to implement SSAI using one of the following:

Create an ad configuration

The ad configuration defines various aspects of SSAI playback, including ad calls, beacons, and other configuration options. Your ad response can be VAST, VMAP or DFP Ad Rules.

For details about creating and managing your ad configurations, see the Video Cloud SSAI Ad Config API document.

Create a Brightcove player

Create a new Brightcove player using Video Cloud Studio. For details, see the Quick Start: Creating and Styling a Player document.

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:

  1. Open the PLAYERS module and locate the player to which you want to add advertising functionality.
  2. Select the link for the player to open the player's properties.
  3. Select Advertising in the left navigation menu.
  4. Check the Enable Server-Side (SSAI) checkbox.
  5. From the Select Configuration dropdown menu, select the ad configuration that you would like to associate with this player.
  6. 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.
  7. The completed form should look similar to this:

    SSAI advertising in Players module
    SSAI advertising in Players module
  8. Select Save.
  9. 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:

  1. Add the SSAI plugin
  2. Associate ads with your player
  3. Play a video with ads

Add the SSAI plugin

You can either add the SSAI plugin files to your HTML code, or you can add it to your player's configuration as shown here:

  1. Open the PLAYERS module and either create a new player or locate the player to which you wish to add the plugin.
  2. Click the link for the player to open the player's properties.
  3. Click Plugins in the left navigation menu.
  4. Next, click Add a Plugin.
  5. For the Plugin Name enter ssai.
  6. For the JavaScript URL, enter:
    https://players.brightcove.net/videojs-ssai/1/videojs-ssai.js
  7. For the CSS URL, enter:
    https://players.brightcove.net/videojs-ssai/1/videojs-ssai.css
  8. You do not have to enter any options for this plugin.
  9. Click Save.
  10. To publish the player, click Publish & Embed > Publish Changes.
  11. To close the open dialog, click Close.

Associate ads with your player

Next, you will associate either your ad configuration to your Brightcove player. You can do this one of three ways:

Standard (iframe) embed code

With the Standard embed code, include the adConfigId query string parameter with the value of your ad config id:

<iframe src="https://players.brightcove.net/1752604059001/default_default/
index.html?videoId=5625751316001&adConfigId=your ad config id"
	allowfullscreen
	webkitallowfullscreen
	mozallowfullscreen
	width="640"
	height="360"></iframe>

Advanced embed code

With the Advanced embed code, include the data-ad-config-id attribute with the value of your ad config id:

<video-js data-video-id="5625751316001"
  data-account="1752604059001"
  data-player="default"
  data-embed="default"
  data-application-id
  data-ad-config-id="your ad config id"
  class="video-js"
  controls
  width="640"
  height="360"></video-js>
<script src="https://players.brightcove.net/1752604059001/default_default/index.min.js"></script>

Using the catalog

You can use the player catalog to associate ads with your video. The catalog works by making two requests:

  1. Request video data from the player catalog. This will include a VMAP URL.
  2. The player source is set with the VMAP URL, triggering a request for a VMAP document from Dynamic Delivery. The player source is set again with a valid VMAP XML document.

When using the catalog with SSAI, append your ad configuration id to the getVideo() call to the Playback API as follows:

var adConfigId = "your ad config id";
var myPlayer = videojs.getPlayer('myPlayerId');
// If you added the SSAI plugin using the Players module, then the initialization
// step is performed automatically. Uncomment the next line if you
// did not use the Players module.
//myPlayer.ssai();

myPlayer.catalog.getVideo("your video id", function(error, video) {
	if (error) {
		myPlayer.error(error);
	} else {
		myPlayer.catalog.load(video);
	}
}, adConfigId);

Updating your player configuration

Another way to associate ads is to include your ad config id in your Brightcove player configuration. To do this, you can use the Player Management API as follows:

  1. Use the PATCH command to include your ad_config_id. Here is an example of updating your player using cURL:

    curl \
      --header "Content-Type: application/json" \
      --user $EMAIL \
      --request PATCH \
      --data '{
          "ad_config_id" : "$CONFIG_ID"
      }' \
      https://players.api.brightcove.com/v1/accounts/$ACCOUNT_ID/players/$PLAYER_ID/configuration
    
  2. You can then publish your changes as follows:

    curl \
      --header "Content-Type: application/json" \
      --user $EMAIL \
      --request POST \
      https://players.api.brightcove.com/v1/accounts/$ACCOUNT_ID/players/$PLAYER_ID/publish
    
  3. Verify that the configuration for your Brightcove player includes ad_config_id set to your config id value and the ssai plugin with the associated plugin files. To do this, follow these steps:

    1. Navigate to your player in the Studio Players module. Click on the player name link to see details.
    2. Select the Embed Code & URL (either Preview or Published will work). Click on the Player URL link.
    3. In the browser address bar, change the index.html to config.json, and browse the new URL.

    Your player configuration should look similar to this:

    {
      "account_id": "1752604059001",
      "ad_config_id": "d6190656-2095-4ff3-8afe-123abcde",
      "compatibility": true,
      "embed_id": "default",
      "player": {
        "template": {
          "name": "single-video-template",
          "version": "6.9.0"
        }
      },
      "player_id": "rJCECV0RZ",
      "player_name": "SSAI Player",
      "plugins": [
        {
          "name": "ssai"
        }
      ],
      "scripts": [
        "https://players.brightcove.net/videojs-ssai/1/videojs-ssai.js"
      ],
      "stylesheets": [
        "https://players.brightcove.net/videojs-ssai/1/videojs-ssai.css"
      ],
      "updated_at": "2017-11-07T16:03:47.161Z",
      "video_cloud": {
        "policy_key": "ABCDE123456789",
        "video": null
      }
    }

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

  1. 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.
  2. 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

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

31 Jan 2018

v1.2.1

  • Make sure we tell contrib-ads we are using stitched ads correctly

18 Jan 2018

v1.2.0

  • Added support for WrapperChain creative extension in VAST documents
  • Fix sending impression, start, quartile, and complete beacons and player events

18 Dec 2017

v1.1.2

  • Ensure that we coerce legacy Once VMAP Content-Type correctly
  • Fixed an issue where the player could be stuck in a state of waiting for a preroll when there was no preroll

15 Dec 2017

v1.1.1

  • Added an option to not put the player in a fake ended state
  • Bug fixes
    • Allow fakeEnded setter to accept false
    • Always report nopreroll and nopostroll events to contrib-ads to prevent strange edge-case issues with states that are not relevant to the SSAI use-case
    • Do a better job of cleaning up overlays between sources and on error events
    • false rather than true should short-circuit fakeEnded logic
    • Remove overlays from player before dispose

16 Nov 2017

v1.0.3

  • Fixed an issue where synchronously setting an SSAI source after initializing the plugin would put the player in a bad state
  • Improved prevention of scrubbing and seeking during ads to prevent stuttering

30 Oct 2017

v1.0.2

  • Ensure that player.ads.ad is available when ads-ad-started is triggered

25 Oct 2017

v1.0.1

  • 1 minute should show as 1:00 not <1:00
  • Adjust timing logic when moving out of ads to avoid flashes of content
  • Skip ad button should only skip one linear ad

12 Oct 2017

v1.0.0

  • Initial release. Support playback of SSAI streams via Brightcove Dynamic Delivery.