## 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.

[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.

[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.

[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.

[Run example in CodeSandbox](🔗)

## What's next

  • [A full example of ads scheduling can be found in our Github repository](🔗)

  • [Setup Bitmovin Player using Google DFP Video Ads](🔗)

  • [Try out your ads with our advertising demo page](🔗)

  • [How can I change the locale language for ads](🔗)