Implementing Server-Side Ads with Brightcove Player

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.

Here's a video overview:

Requirements

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.

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

Brightcove SSAI 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 SSAI 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, follow these steps:

1. Create an ad configuration
2. Create a Brightcove Player
3. Implement SSAI using Studio

That's it. Your Brightcove Player is now configured for Server-side ads. If you prefer, you can add SSAI programmatically, as shown in the Implement SSAI programmatically section.

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 GAM Ad Rules. To create an ad configuration, follow these steps:

1. In Video Cloud Studio, expand the ADMIN menu and select Server-Side Ad Settings.

   

2. Add information for your ad configuration and select Save.

   

For details, see the Configuring Server-Side Ad Settings document.

To create an ad configuration using the SSAI API, 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 Video Cloud Basics: Creating 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:

   

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

You can easily add SSAI to your player using Video Cloud Studio, as shown in the previous section. If you prefer to do this programmatically, follow these steps:

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. From the Add a Plugin dropdown, select Custom Plugin.

   

5. For the Plugin Name enter ssai.
6. For the JavaScript URL, enter:

   https://players.brightcove.net/videojs-ssai/2/videojs-ssai.js

7. For the CSS URL, enter:

   https://players.brightcove.net/videojs-ssai/2/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 embed code
• Advanced embed code
• Using the catalog
• Updating your player configuration

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
  allow="encrypted-media"
  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"
  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": "7.7.0"
       }
     },
     "player_id": "rJCECV0RZ",
     "player_name": "SSAI Player",
     "plugins": [
       {
         "name": "ssai"
       }
     ],
     "scripts": [
       "https://players.brightcove.net/videojs-ssai/2/videojs-ssai.js"
     ],
     "stylesheets": [
       "https://players.brightcove.net/videojs-ssai/2/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.
• vmapURLParams

  An object containing the parameters for replacing arbitrary values in VMAP content URLs. See the SSAI - URL Variables section.

  • vmapURLParams.* - The object keys can have any name. The name of this property must match the VMAP source URL param sub-string with the format ❴❴url.*❵❵, or else it will not be replaced.

    Example: In the case where vmapURLParams is set to an object { foo: 123, bar: 'test' }:

    • The original VMAP source URL:

      .../content.vmap?bc_token=1234

    • Will be updated to:

      .../content.vmap?bc_token=1234&foo=123&bar=test

Styling

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

Methods/properties

Several public methods are available when using the SSAI plugin. Remember, you can also use the standard player methods.

To use the SSAI methods, your JavaScript code will need to wait for the plugin to be loaded, as shown here:

<script>
  videojs.getPlayer('myPlayerID').ready(function () {
    var myPlayer = this;
    myPlayer.on("loadedmetadata", function () {
      console.log(myPlayer.ssai().currentTimelineState());
    });
  });
</script>

Timeline state methods

The *TimelineState methods return a TimelineState object. A timeline state object is a plain object with a specific interface that details the playback state of an SSAI stream at any point in the absolute timeline.

The "absolute time" refers to a point in the complete timeline of a stream (with both ads and content included). The term "relative time" refers to the time relative to the current content (either ad or content).

contentTimelineState()

• Argument: single numeric time
• Get the timeline state at the specified content time (content, not counting ads). For example, if your content is 100 seconds long, you can get the timeline state at halfway through the content using:

  contentTimelineState(50)

absoluteTimelineState()

• Argument: single numeric time
• Get the timeline state at the specified absolute time (content + ads). For example, if your content includes a 30 second pre-roll ad, you can get the timeline state at 30 seconds into your content using:

  absoluteTimelineState(50)

Here is a list of additional timeline state methods:

currentTimelineState()
relativeTimelineState()
seekInAbsoluteTime()
seekInRelativeTime()
seekInContentTime()

Timeline state properties

To get the value of a timeline state property, you can use the following syntax:

myPlayer.ssai().absoluteTimelineState().absoluteDuration;

Here is a list of properties associated with the TimelineState object:

absoluteTime

• Type: Number
• The absolute time in the stream.

absoluteDuration

• Type: Number
• The absolute duration of the stream.

relativeTime

• Type: Number
• The time in the stream relative either to the current linear ad or to the content itself.

relativeDuration

• Type: Number
• The duration of the current linear ad or the content itself.

linearAdRoll

• Type: LinearAdRoll
• An object representing the current linear ad for the absolute time.

linearAd

• Type: LinearAd
• An object representing the current linear ad for the absolute time.

Events

At the current time there is one SSAI-specific event dispatched by this plugin.

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 an SSAI stream. Traditional video players only have a concept of content time; times between start and end of the URI it is currently playing. Because an SSAI 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.

• Content time refers to a point in time within the content timeline of an SSAI stream - ignoring all ads. For example, a 2:00 video with a 0:30 pre-roll ad has a content time of 2:00. The content time of 0:15 is equivalent to an absolute time of 0:45 (pre-roll plus 15 seconds).

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.

Notes

SSAI VOD

• If you build custom implementations on top of the Brightcove Playback API (PAPI) responses, please note the following:
  • With Server-Side Ad Insertion (SSAI), the thumbnails manifest is located in the VMAP instead of the PAPI response.
  • With non-SSAI, the thumbnails manifest is included in the PAPI response.
• For a list of limitations, see the SSAI Overview document.

SSAI Live

• VMAP for Live SSAI is not currently supported.
• SSAI for live playback does not require the SSAI plugin, and client-side features for SSAI playback are not available for live.
• For a list of limitations, see the Brightcove Live API with SSAI document.

SSAI midroll behavior

• When a user seeks past a midroll ad without watching it, the ad will play before the content resumes.
• When a user seeks past a midroll ad after having watched the ad, the player will skip the midroll ad.

Changelog

See the SSAI Plugin Release Notes.

For historical release notes, see the changelog here.