How to set up VAST and VMAP ads on iOS

This article explains how to schedule client-side VAST and VMAP advertisements through THEOplayer.

• A VAST advertisement is a single ad break, and you can position it as a pre-roll, mid-roll or post-roll.
• A VMAP advertisement is a playlist of ad breaks, and can contain any combination of pre-rolls, mid-rolls and/or post-rolls.

Through the THEOplayer API, app developers can define which "ad integration" they want to use. Scheduling VAST and VMAP ads through all ad integrations is very similar, so consider this article as a reference guide.

On iOS and tvOS, client-side advertisements are scheduled through the Google IMA ad integration, so make sure to set it up before starting.

VAST

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. https://cdn.theoplayer.com/demos/ads/vast/vast.xml) with a time offset.

You may also schedule multiple ad tags.

Let's consider the following common use-cases:

1. Scheduling a single pre-roll
2. Scheduling two pre-rolls, two mid-rolls and one post-roll

Scheduling a single pre-roll

You configure a GoogleImaAdDescription in the ads property of your SourceDescription.

In this GoogleImaAdDescription,

• You set an ad tag URL.
• You set the value of timeOffset to "start" (or 00:00:00 or 0%) to indicate that it's a pre-roll.

private var source: SourceDescription {
    // Declare a TypedSource object with a stream URL and its type
    let typedSource = TypedSource(
        src: videoUrl,
        type: mimeType
    )

    // The AdDescription object that defines the IMA ad to be played.
    let offset = "start",
    let adDescription: GoogleImaAdDescription = GoogleImaAdDescription(src: adTagUrl, timeOffset: offset)

    // Returns a computed SourceDescription object
    return SourceDescription(
        source: typedSource,
        ads: [adDescription],
        poster: posterUrl
    )
}

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 two pre-rolls, two mid-rolls and one post-roll

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.

let typedSource = TypedSource(src: "https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8", type: "application/x-mpegurl")

let vastAdTag = "https://cdn.theoplayer.com/demos/ads/vast/vast.xml"
let ad1 = GoogleImaAdDescription(src : vastAdTag, timeOffset: "start")
let ad2 = GoogleImaAdDescription(src : vastAdTag, timeOffset: "start")
let ad3 = GoogleImaAdDescription(src : vastAdTag, timeOffset: "00:00:15")
let ad4 = GoogleImaAdDescription(src : vastAdTag, timeOffset: "00:00:15")
let ad5 = GoogleImaAdDescription(src : vastAdTag, timeOffset: "end")
let source = SourceDescription(source : typedSource, ads: [ad1, ad2, ad3, ad4, ad5])

theoplayer.source = source

Skippable ads

To allow viewers to skip an ad, leverage the skipOffset property in your VAST (or VMAP) file, and adhere to the VAST standard, because this offers the widest support across ad integrations and platforms.

VMAP

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 time offset helps VAST ads to play at a specific timestamp. VMAP ads can define that behavior inside their manifest file, thus they should not have a timeOffset parameter. This property may not be configured for ad types other than VAST. Setting a timeOffset on a VMAP ad will cause your ads not to be scheduled correctly, unless you explicitly configured an AdSource.type, in which case timeOffset will be ignored. This is because the player must decide up front when to load the ad source: VMAP ads must be loaded immediately in order to schedule them correctly, while loading a VAST ad can be deferred until right before the timeOffset at which to play them. Therefore, if a timeOffset is configured without an explicit AdSource.Type, the player will assume that it's a VAST ad.

The snippet below demonstrates how to configure a VMAP advertisement.

let typedSource = TypedSource(src: "https://cdn.theoplayer.com/video/elephants-dream/playlist.m3u8", type: "application/x-mpegurl")

let vmapSource = "https://cdn.theoplayer.com/demos/ads/vmap/single-pre-mid-post-no-skip.xml"
let ad = GoogleImaAdDescription(src : vmapSource)

let source = SourceDescription(source : typedSource, ads: [ad])
theoplayer.source = source

Dynamic scheduling

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 schedule 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 to schedule an ad at the 30 seconds mark. To achieve this, you would set timeOffset: "00:00:30", and not timeOffset: "00:00:10", because this would be 10 seconds in the past, and the ad would instantly start playing.

Invoking the following example function when the video is already playing will instantly schedule the VAST ad to be played:

theoplayer.ads.schedule(adDescription: GoogleImaAdDescription(src: "https://cdn.theoplayer.com/demos/ads/vast/vast.xml"))

Resources

• Samples for iOS SDK