Setting up Ads with the Web Player

Introduction to Advertising

Bitmovin Player is capable of serving Ads out of the box. This guide is made to quickly help get you started on configuring it with your integration.

There are two ways that Ads can be configured with Bitmovin Player. One option is to use static configuration in the player config object, and the other is to schedule them dynamically using PlayerAdvertisingAPI.

We will cover both cases in this tutorial. However, in case you are new to the whole advertising topic, we will start by covering terms that will often appear along all the advertising related docs. If you are already familiar with these basic concepts feel free to jump to the next section.

The basic unit of the advertising API is called an AdBreak. It represents a specific time slot within the streamed content dedicated to ads playback. AdBreaks are configured with a position and a tag where the position refers to a specific point on the stream timeline while the tag contains information about which sources that AdBreak should load Ads from. Typically this is a URL pointing to your Ad server that will return a response in a supported format: VAST, VMAP or VPAID. You can check IAB Tech Lab resources to learn more about these formats.

When the Bitmovin Player Advertising Module starts to play an AdBreak at its position, it unloads the main content and plays the advertisement using the player API. However, this switching between ads and main content does not count as a player impression. The ad playback is started automatically and there are also AdBreakStarted and AdBreakFinished player events triggered to signal this transition. This is because during the ad playback all the calls to player API will only return values related to that specific advertising content.

Now that we have covered the basic concepts, let's explore how to setup such an AdBreak with your content.

Static Ads configuration

The easiest way to configure Ads is by adding the advertising property to the player configuration object. All that needs to be provided is a URL pointing to a target Ad server along with the type of advertising tag. We will also use the Bitmovin Advertising Module to gain more control and additional features.

Simple Pre-roll with Static Configuration

The following example showcases this, and will play the configured AdBreak as a pre-roll. "Pre-roll" means that the ad will start playing before the main content, and is the default value for the position property, if it is not explicitly defined.

var playerConfig = {
  key: '<PLAYER_LICENSE_KEY>',
  advertising: {
    adBreaks: [
      {
        tag: {
          type: 'vast',
          // More Ad Samples can be found here:
          // https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/tags
          url:
            'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dskippablelinear&correlator='
        }
      }
    ]
  }
};

// By default, the Bitmovin Player uses the IMA Advertising Module.
// Here we activate the Bitmovin Advertising Module instead, which gives you more control.
bitmovin.player.Player.addModule(window.bitmovin.player['advertising-bitmovin'].default);

var player = new bitmovin.player.Player(document.getElementById('player'), playerConfig);

Run example in CodeSandbox

Dynamic Ads scheduling

To gain more flexibility, it is also possible to schedule an AdBreak dynamically in code using the PlayerAdvertisingAPI exposed by the Bitmovin Player instance. To do this, you need to call the player.ads.schedule method.

This method expects an object with the following layout:

tag: an AdBreakConfig containing an Ad tag
id: a user-defined Id
position: the string 'pre', the string 'post' or a string with numeric value representing the break time position.

Please note that in order to activate this API, at least an empty object assigned to advertising property needs to be present in the player configuration.

During the ad playback it is possible to call player.ads.skip method to skip the Ad currently being played.

More details on the Bitmovin Player Advertising API is available here.

Start Playback at Specific Position

Here is a first simple example of dynamic AdBreak scheduling where Ad playback is positioned to the 15th second of main content.

var playerConfig = {
  key: '<PLAYER_LICENSE_KEY>',
  // This won't configure any ads but it will make the PlayerAdvertisingAPI available
  advertising: {},
};

// By default, the Bitmovin Player uses the IMA Advertising Module.
// Here we activate the Bitmovin Advertising Module instead, which gives you more control.
bitmovin.player.Player.addModule(window.bitmovin.player['advertising-bitmovin'].default);
var player = new bitmovin.player.Player(document.getElementById('player'), playerConfig);

player.ads.schedule({
  tag: {
    url: 'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dskippablelinear&correlator=',
    type: 'vast'
  },
  id: 'Ad',
  position: '15',
});

Run example in CodeSandbox

Schedule Immediate AdBreak

It is also possible to control the advertising flow manually and schedule the AdBreak to be played immediately based on some event.
In the following example we react to the click of a button to schedule an immediate ad break.

var playerConfig = {
  key: '<PLAYER_LICENSE_KEY>',
  // This won't configure any ads but it will make the PlayerAdvertisingAPI available
  advertising: {},
};

// By default, the Bitmovin Player uses the IMA Advertising Module.
// Here we activate the Bitmovin Advertising Module instead, which gives you more control.
bitmovin.player.Player.addModule(window.bitmovin.player['advertising-bitmovin'].default);
var player = new bitmovin.player.Player(document.getElementById('player'), playerConfig);

function scheduleImmediateAdBreak() {
  // Current playback position of the main content
  var currentTime = player.getCurrentTime();
  player.ads.schedule({
    tag: {
      url: 'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dskippablelinear&correlator=',
      type: 'vast'
    },
    id: 'Ad',
    position: currentTime.toString(),
  });
}

// Use a button to schedule an ad whenever its clicked
var scheduleBtn = document.getElementById('scheduleBtn');
skipBtn.addEventListener('click', function () {
  scheduleImmediateAdBreak();
});

// Use this button to let the user skip the current ad
var skipBtn = document.getElementById('skipButton');
skipBtn.addEventListener('click', function () {
  player.ads.skip();
});

Run example in CodeSandbox

Schedule AdBreak After Specific Time of Playback

Dynamic ads scheduling gives you full control over the advertising configuration, and allows you to define custom logic around how often to play advertising. In the following advanced example we play the advertisement after a specific amout of playback time, rather than binding the AdBreak to a specific position in the timeline.

This is achieved by observing the player TimeChanged event to see how much time elapsed. As soon as the threshold is reached, we can trigger the Ad scheduling.

var playerConfig = {
  key: '<PLAYER_LICENSE_KEY>',
  // This won't configure any ads but it will make the PlayerAdvertisingAPI available
  advertising: {},
};

// By default, the Bitmovin Player uses the IMA Advertising Module.
// Here we activate the Bitmovin Advertising Module instead, which gives you more control.
bitmovin.player.Player.addModule(window.bitmovin.player['advertising-bitmovin'].default);
var player = new bitmovin.player.Player(document.getElementById('player'), playerConfig);

function scheduleImmediateAdBreak() {
  // Current playback position of the main content
  var currentTime = player.getCurrentTime();
  player.ads.schedule({
    tag: {
      url: 'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dskippablelinear&correlator=',
      type: 'vast'
    },
    id: 'Ad',
    position: currentTime.toString(),
  });
}

// Observe player `TimeChanged` event and schedule the immediate `AdBreak` when it reached the threshold
var timePlayed = 0;
player.on('timechanged', function(event) {
  if (timePlayed >= 15) {
    scheduleImmediateAdBreak();
    timePlayed = 0;
  } else {
    timePlayed = event.time;
  }
});

Run example in CodeSandbox

Introduction to Advertising

Static Ads configuration

Simple Pre-roll with Static Configuration

Dynamic Ads scheduling

Start Playback at Specific Position

Schedule Immediate AdBreak

Schedule AdBreak After Specific Time of Playback

What's next