Setting up Ads with the Web Player
Bitmovin Player is capable of serving Ads out of the box. This guide will help you get started with configuring Ads for your integration.
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);
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
: anAdBreakConfig
containing an Adtag
id
: a user-defined Idposition
: 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',
});
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();
});
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;
}
});
What's next
Updated 18 days ago