SSAI: Ad Block Detection and Auto-Failover

Video Cloud
Brightcove Player
Player Developer

In this topic, you will learn how to turn on a Brightcove Player's auto-failover setting to request SSAi (Server Side Ads Insertion) ads when ad blockers are detected.


With ad failover turned on, when Brightcove Player detects an ad blocker present in the browser the player will automatically request an SSAI stream. Otherwise, it will use IMA ads.


  • Ad blocker detection is very reliable, but not 100%.
  • Customers using this feature must be using Dynamic Delivery.
  • Only IMA and SSAI plugins are supported (no FreeWheel or OnceUX).

Player sample

Here is a sample player configured with ad failover and IMA3 ads.

  • If you run this sample in a browser without an ad blocker, you should see a DFP inline skippable ad by Google. This is the IMA3 preroll ad.
  • If you run this sample in a browser with an ad blocker, you should see a Brightcove guide to digital marketing ad. This is the Server-Side ad (SSAI) as defined in our ad configuration.

See the Pen SSAI Ad Failover with hook by Brightcove Learning Services (@rcrooks1969) on CodePen.

Configure using Players module

The Players module can be used to enable ad block detection on the client-side with server-side failover. Note that these steps are not supported when using the Legacy Players module. To do this, follow these steps:

  1. Open the Players module.
  2. Click on a player name to open the player properties.
  3. Click Advertising in the left navigation.
  4. Select the Enable Client-Side (IMA) option and configure the IMA options. For information on configuring client-side advertising, see Configuring Player Advertising using the Players Module.
  5. Select the Enable Server-Side (SSAI) option. Note that the server-side option will not appear unless your account has been enabled for SSAI.

Configure the player

For ad failover to function you must have the player configured correctly. The following three configuration changes need to be done:

  1. The player configuration must have "ad_failover": true at the top level. This is done using a curl statement. The following would add the desired configuration to an existing player:

    // Configure ad failover
    curl \
    --header "Content-Type: application/json" \
    --user $EMAIL \
    --request PATCH \
    --data '{
    "ad_failover": true
    }' \$ACCOUNT_ID/players/$PLAYER_ID/configuration

    If you are unfamiliar with curl, see the Quick Start: Player Management document to get started.

  2. Both the IMA and SSAI plugins must be configured for the player. This is normally an invalid configuration, and the player would log a warning to the console, but having the "ad_failover": true configuration makes it valid. Both of these plugins can be added in Studio, or via a curl statement. A valid example player configuration is show here:

    "account_id": "1507807800001",
    "ad_failover": true,
    "compatibility": true,
    "embed_id": "default",
    "player": {
    	"template": {
    	"name": "single-video-template",
    	"version": "6.23.0"
    "player_id": "i6gmOmJiFx",
    "player_name": "ad failover testing",
    "plugins": [{
    	"name": "ssai"
    	}, {
    	"injected_version": "3.2.0",
    	"name": "ima3",
    	"options": {
    	"adTechOrder": [
    	"hardTimeouts": true,
    	"requestMode": "onload",
    	"serverUrl": "",
    	"timeout": 4000,
    	"useMediaCuePoints": false,
    	"vpaidMode": "ENABLED"
    "registry_id": "@brightcove/videojs-ima3",
    "version": "3.x"
    "scripts": [
    "stylesheets": [
    "updated_at": "2018-09-17T13:53:01.905Z",
    "video_cloud": {
    "policy_key": "BCpkADawqM1U6pz...67I3",
    "video": null
  3. There must be an ad configuration ID (ad_config_id) available via the configuration or defined at runtime. Although technically not required, not having one means no ads in an SSAI stream would be available, which defeats the purpose of ad failover.

    To supply an ad configuration ID at runtime using the Advanced (in-page embed) player implementation, you supply the ID as an attribute in the <video> tag:

    <script src="https://.../index.min.js"></script>

    If you are using an Standard (iframe) player implementation you would supply the ad configuration ID as follows:

    <iframe src="https://.../index.html?adConfigId=xyz-456" allowfullscreen webkitallowfullscreen mozallowfullscreen></iframe>
  4. When using ad failover, you need to wait for player initialization to determine if ad block has been detected. The following code uses a setup hook to wait for the player to be ready before calling the IMA3 plugin with the ad URL. For details about using hooks, see Video.js hooks documentation.

    var myPlayer,
    videojs.hook('setup', function(myPlayer){
    	myPlayer.ready(function() {
    	if (myPlayer.usingPlugin('ima3')){
    			myPlayer.ima3.settings.serverUrl = serverUrl;