This article explains how to schedule client-side VAST and VMAP advertisements through THEOplayer.
Through the THEOplayer API, app developers can define which "ad integration" they want to use. THEOplayer currently supports 4 types of client-side ad integrations:
This article explains scheduling VAST and VMAP ads through the "default" ad integration. Scheduling VAST and VMAP ads through other ad integrations is very similar, so consider this article as a reference guide. For example, if you use Google Ad Manager (i.e. DoubleClick), then this article allows you to better understand how to schedule VAST and VMAP ads, but you want to use the Google IMA integration (and API) to actually implement it in your app.
Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK | Roku SDK |
---|---|---|---|---|---|---|
Yes | Yes | Yes | Yes | Yes | No | No |
Setting up a client-side VAST advertisement means scheduling a VAST ad tag.
As an app developer, you associate a VAST ad tag (URL) (e.g. //cdn.theoplayer.com/demos/ads/vast/vast.xml
) with a time offset.
Additionally, when using the default ad integration, you can also specify after how many seconds a VAST ad may be skipped.
You may also schedule multiple ad tags.
Let's consider the following common use-cases:
The following snippets demonstrate how to schedule a single pre-roll.
You configure one AdDescription
in the ads
property of your SourceConfiguration
.
In this AdDescription
,
sources
to your ad tag URL.timeOffset
to "start"
(or 00:00:00
or 0%
) to indicate that it's a pre-roll. player.source = {
"sources": [
{
"src": "//cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8"
}
],
"ads": [
{
"sources": "//cdn.theoplayer.com/demos/ads/vast/vast.xml",
"timeOffset": "start"
}
]
}
If you wanted to schedule a post-roll instead of a pre-roll, you set the value of timeOffset
to "end"
.
If you want to schedule a mid-roll instead of a pre-roll, you set the value of timeOffset
to the HH:MM:SS
format.
For example, to schedule an advertisement at the 15s mark, you set the value of timeOffset
to "00:00:15"
.
You configure one AdDescription
in the ads
property of your SourceDescription
.
In this AdDescription
,
sources
to your ad tag URL.timeOffset
to "start"
(or 00:00:00
or 0%
) to indicate that it's a pre-roll. TypedSource typedSource = TypedSource.Builder
.typedSource("https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8")
.build();
String vastAdTag = "//cdn.theoplayer.com/demos/ads/vast/vast.xml";
String offset = "start";
AdDescription ad = THEOplayerAdDescription.Builder.adDescription(vastAdTag).timeOffset(offset).build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription(typedSource)
.ads(ad)
.build();
theoplayerView.getPlayer().setSource(sourceDescription);
If you wanted to schedule a post-roll instead of a pre-roll, you set the value of timeOffset
to "end"
.
If you want to schedule a mid-roll instead of a pre-roll, you set the value of timeOffset
to the HH:MM:SS
format.
For example, to schedule an advertisement at the 15s mark, you set the value of timeOffset
to "00:00:15"
.
You configure one THEOAdDescription
in the ads
property of your SourceDescription
.
In this AdDescription
,
sources
to your ad tag URL.timeOffset
to "start"
(or 00:00:00
or 0%
) to indicate that it's a pre-roll. let typedSource = TypedSource(src: "https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8", type: "application/x-mpegurl")
let vastAdTag = "//cdn.theoplayer.com/demos/ads/vast/vast.xml"
let offset = "start"
let ad = THEOAdDescription(src : vastAdTag, timeOffset: offset)
let source = SourceDescription(source : typedSource, ads: [ad])
theoplayer.source = source
If you wanted to schedule a post-roll instead of a pre-roll, you set the value of timeOffset
to "end"
.
If you want to schedule a mid-roll instead of a pre-roll, you set the value of timeOffset
to the HH:MM:SS
format.
For example, to schedule an advertisement at the 15s mark, you set the value of timeOffset
to "00:00:15"
.
Scheduling multiple VAST ads is only slightly different from scheduling a single VASt ad. Instead of passing along one ad description to your array, you pass along multiple ad descriptions to the array.
The following snippets demonstrate how you'd configure two pre-rolls, two mid-rolls and one post-roll through the usage of VAST ads.
player.source = {
"sources": [
{
"src": "//cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8"
}
],
"ads": [
{
"sources": "//cdn.theoplayer.com/demos/ads/vast/vast.xml",
"timeOffset": "start"
},
{
"sources": "//cdn.theoplayer.com/demos/ads/vast/vast.xml",
"timeOffset": "start"
},
{
"sources": "//cdn.theoplayer.com/demos/ads/vast/vast.xml",
"timeOffset": "00:00:15"
},
{
"sources": "//cdn.theoplayer.com/demos/ads/vast/vast.xml",
"timeOffset": "00:00:30"
},
{
"sources": "//cdn.theoplayer.com/demos/ads/vast/vast.xml",
"timeOffset": "end"
}
]
}
TypedSource.Builder typedSource = TypedSource.Builder
.typedSource("https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8");
SourceDescription.Builder sourceDescription = SourceDescription.Builder
.sourceDescription(typedSource.build());
sourceDescription.ads(
THEOplayerAdDescription.Builder
.adDescription("//cdn.theoplayer.com/demos/ads/vast/vast.xml")
.timeOffset("start")
.build(),
THEOplayerAdDescription.Builder
.adDescription("//cdn.theoplayer.com/demos/ads/vast/vast.xml")
.timeOffset("start")
.build(),
THEOplayerAdDescription.Builder
.adDescription("//cdn.theoplayer.com/demos/ads/vast/vast.xml")
.timeOffset("00:00:15")
.build(),
THEOplayerAdDescription.Builder
.adDescription("//cdn.theoplayer.com/demos/ads/vast/vast.xml")
.timeOffset("00:00:15")
.build(),
THEOplayerAdDescription.Builder
.adDescription("//cdn.theoplayer.com/demos/ads/vast/vast.xml")
.timeOffset("end")
.build()
);
theoplayerView.getPlayer().setSource(sourceDescription.build());
let typedSource = TypedSource(src: "https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8", type: "application/x-mpegurl")
let vastAdTag = "//cdn.theoplayer.com/demos/ads/vast/vast.xml"
let ad1 = THEOAdDescription(src : vastAdTag, timeOffset: "start")
let ad2 = THEOAdDescription(src : vastAdTag, timeOffset: "start")
let ad3 = THEOAdDescription(src : vastAdTag, timeOffset: "00:00:15")
let ad4 = THEOAdDescription(src : vastAdTag, timeOffset: "00:00:15")
let ad5 = THEOAdDescription(src : vastAdTag, timeOffset: "stop")
let source = SourceDescription(source : typedSource, ads: [ad1, ad2, ad3, ad4, ad5])
theoplayer.source = source
When using the "default" ad integration, you can define when an VAST ad can be skipped through the skipOffset
property.
However, it is recommended to leverage the skipOffset
property in your VAST (or VMAP) file instead, and adhere to the VAST standard,
because this offers the widest support across ad integrations and platforms.
The following snippets demonstrate how to allow viewers to skip a mid-roll after 5 seconds.
Note that the skipOffset
property is not supported when using other ad integrations, such as Google IMA, SpotX and FreeWheel (because we're dependent on third-party APIs).
player.source = {
"sources": [
{
"src": "//cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8"
}
],
"ads": [
{
"sources": "//cdn.theoplayer.com/demos/ads/vast/vast.xml",
"timeOffset": "00:00:15",
"skipOffset": "5"
}
]
}
TypedSource.Builder typedSource = TypedSource.Builder
.typedSource("https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8");
SourceDescription.Builder sourceDescription = SourceDescription.Builder
.sourceDescription(typedSource.build());
sourceDescription.ads(
THEOplayerAdDescription.Builder
.adDescription("//cdn.theoplayer.com/demos/ads/vast/vast.xml")
.timeOffset("00:00:15")
.skipOffset("5")
.build()
);
theoplayerView.getPlayer().setSource(sourceDescription.build());
let typedSource = TypedSource(src: "https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8", type: "application/x-mpegurl")
let ad = THEOAdDescription(src : "//cdn.theoplayer.com/demos/ads/vast/vast.xml", timeOffset: "00:00:15", skipOffset: "5")
let source = SourceDescription(source : typedSource, ads: [ad])
theoplayer.source = source
Scheduling a VMAP advertisement is similar to scheduling a VAST advertisement.
However, you don't define the timeOffset
, because the VMAP playlist defines the offsets of each ad break it contains.
The snippets below demonstrate how to configure a VMAP advertisement.
// Declare a VMAP ad source. No timeOffset here, because the VMAP itself arranges this.
let vmapSource =
"//cdn.theoplayer.com/demos/ads/vmap/single-pre-mid-post-no-skip.xml";
let ad = [{ sources: vmapSource }];
let source = {
sources: [typedSource],
ads: ad,
};
player.source = source;
TypedSource typedSource = TypedSource.Builder
.typedSource(getString(R.string.defaultSourceUrl))
.build();
String vmapSource = "//cdn.theoplayer.com/demos/ads/vmap/single-pre-mid-post-no-skip.xml";
AdDescription ad = THEOplayerAdDescription.Builder.adDescription(vmapSource).build();
SourceDescription sourceDescription = SourceDescription.Builder.sourceDescription(typedSource)
.ads(ad)
.build();
tpv.getPlayer().setSource(sourceDescription);
let typedSource = TypedSource(src: "https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8", type: "application/x-mpegurl")
let vmapSource = "//cdn.theoplayer.com/demos/ads/vmap/single-pre-mid-post-no-skip.xml"
let ad = THEOAdDescription(src : vmapSource)
let source = SourceDescription(source : typedSource, ads: [ad])
theoplayer.source = source
If you've read our Advertising User Guide, you might have picked up that you can also dynamically schedule VAST advertisements in THEOplayer. All previous samples in this article use static, pre-defined scheduling -- you schedule the ads whenever you schedule the stream. With dynamic scheduling, you schedule ads at runtime.
You use the Ads
interface to schedule an Ad Description
at runtime.
More specifically, you invoke the ads.schedule(<yourAdDescription>)
function when your video is already playing.
Note that specifying the timeOffset
is optional, and that this value is an absolute value.
For example, let's consider that your current playhead position is at the 20 seconds mark,
and that you want a and you schedule an ad at the 30 seconds mark. To achieve this, you would set timeOffset: "00:00:30"
,
and not to timeOffset: "00:00:10"
, because this would be 10 seconds in the past, and the ad would instantly start playing.
The following samples illustrate the schedule
function across different SDKs.
Invoking the following function when the video is already playing will instantly schedule the VAST ad to be played.
player.ads.schedule({
"sources": "//cdn.theoplayer.com/demos/ads/vast/vast.xml"
});
Invoking the following function when the video is already playing will instantly schedule the VAST ad to be played.
theoplayerView.getPlayer().getAds().schedule(THEOplayerAdDescription.Builder.adDescription("//cdn.theoplayer.com/demos/ads/vast/vast.xml").build());
Invoking the following function when the video is already playing will instantly schedule the VAST ad to be played.
player.ads.schedule(adDescription: THEOAdDescription(src: "//cdn.theoplayer.com/demos/ads/vast/vast.xml"))