Docs | Android

Advertisement layout management

With Ad Layout config app can create its own AdBreak timeline using your VAST tags. AdBreak can be set as Pre, Mid and Post rolls and each AdBreak can contain a single VAST tag or multiple tags, either as a AdPod, but also as a Waterfall.

Important: IMA plugin must be active to enable this feature.

Table of Contents

Single Ad

Here’s a simple scheme sample which contains 4 ad breaks: 1 pre-roll, 2 mid-rolls and 1 post-roll:


// Create list of VAST URL 
val prerollAd = listOf(PRE_ROLL_VAST_URL)

// Create Preroll AdPod
val prerollAdPod = listOf(prerollAd)

// Create AdBreak (Preroll)
val prerollAdBreak = AdBreak(AdBreakPositionType.POSITION, 0, prerollAdPod)

// Create list of VAST URL 
val midrollAd1 = listOf(MID_ROLL_VAST_URL)

// Create Midroll AdPod
val midrollAdPod1 = listOf(midrollAd1)

// Create AdBreak (Midroll)
val midrollAdBreak1 = AdBreak(AdBreakPositionType.POSITION, 15, midrollAdPod1)

// Create list of VAST URL 
val midrollAd2 = listOf(MID_ROLL_VAST_URL)

// Create Midroll AdPod
val midrollAdPod2 = listOf(midrollAd2)

// Create AdBreak (Midroll)
val midrollAdBreak2 = AdBreak(AdBreakPositionType.POSITION, 30, midrollAdPod2)

// Create list of VAST URL 
val postrollAd = listOf(POST_ROLL_VAST_URL)

// Create Postroll AdPod
val postrollAdPod = listOf(postrollAd)

// Create AdBreak (Postroll)
val postrollAdBreak = AdBreak(AdBreakPositionType.POSITION, -1, postrollAdPod)

In this sample, the player will try to request and play 4 ads. Note: position: 0 means pre-roll. position: -1 means post-roll.

Ad Pod

An ad break may contain a list of ads, also referred to as ad pod.

Ad Pod definition (from IAB): An individual ad pod is a group of ads expected to play back-to-back in one commercial ad break similar to how consumers experience commercial ad breaks in broadcast television. An ad pod can be of varying lengths and can be inserted at any point in a stream of content (pre, mid, or post).

Ad pod sample: Again create a list for another Ad and add that in the ad pod list.


// Create list of VAST URL 
val midrollAd1 = listOf(MID_ROLL_VAST_URL_1)

val midrollAd2 = listOf(MID_ROLL_VAST_URL_2)

// Create Midroll AdPod
val midrollAdPod = listOf(midrollAd1, midrollAd2)

// Create AdBreak (Midroll)
val midrollAdBreak1 = AdBreak(AdBreakPositionType.POSITION, 15, midrollAdPod)

In this sample, the player will try to request and play 2 ads in 2 ad pods and play the ad one after another.

Waterfalling

Waterfalling (“daisy chain”) is a process used by publishers selling ads in order to get a better fill-rate. This process can be implemented on the ad server itself, but it can also be implemented on the client - which is what we did. The process is rather simple: if the first ad server doesn’t have any ads to serve, a call to a second server is made etc. Meaning, if the first priority server did not “purchase” the impression, it would cascade down to the next server and to the next, until someone bought it. The same process is applied also if the ad server returned an error (or the client failed to communicate with it), and then it would cascade to the next server and to the next…

An application may want to set a fallback vast url, so in case the primary ad request had failed, the ad won’t be skipped. This mechanism called Waterfalling, is configurable easily using the ad layout config. Here’s a sample of a mid-roll with waterfalling:

// Create list of VAST URL 
val midrollAd = listOf(MID_ROLL_VAST_URL_1, MID_ROLL_VAST_URL_2)

// Create Midroll AdPod
val midrollAdPod = listOf(midrollAd)

// Create AdBreak (Midroll)
val midrollAdBreak1 = AdBreak(AdBreakPositionType.POSITION, 15, midrollAdPod)

Important: A fallback url (e.g. MID_ROLL_VAST_URL_2) will be only used if the previous request (MID_ROLL_VAST_URL_1) is failed. Hence, In this sample, only one ad will be played. Note: There is no limit to the fallback url list.

AdvertisingConfig

This is the primary object needs to be created. It has 4 parameters.

List<AdBreak?> : Create a list of AdBreaks. These AdBreaks will actually be used for Ad playback.

AdTimeUnit : App can configure the Ad’s time either in ‘Seconds’ or ‘MilliSeconds’. This value will be applicable for AdBreak’s position parameter. Ex: 15 seconds or 15000 milliseconds for the ad playback.

AdType : App is configuring the VAST urls or VAST XML response in the AdBreak. Mixing of VAST url and VAST response in one AdLayout configuration is not allowed.

playAdsAfterTime: Play ads only from a specific time.

returnToLive: Default is false - Only for Live Medias (If true then after ad playback,player will go to the live edge else it will try to resume from the same position, if possible). This flag is only functional for Live + DVR medias because Live medias are always playing on the live edge.

AdBreak

AdBreak is the object which will actually be played on the given time.

AdBreakPositionType : Each ad break in the adBreaks list gets the following options:

Note

Preroll and Postroll should not be configured with EVERY.

If Preroll & Postroll can be set as ‘0’ and ‘100’ respectively with PERCENTAGE.

With EVERY, more than 1 Midrolls can not be configured. If configured, 1st AdBreak will be considered, rest will be discarded. Because EVERY means that app wants to play this Ad on a given frequency (Ex: Every 60 seconds till the media ends)

EVERY and PERCENTAGE both are not allowed to the Midrolls at the same time.

Play Ads After Time

An application may want to configure the player to play ads only from a specific time. This can be achieved by playAdsAfterTime parameter on AdvertisingConfig. For example:

AdvertisingConfig(listOf(
            prerollAdBreak,
            midrollAdBreak,
            postrollAdBreak),
            AdTimeUnit.SECONDS, AdType.AD_URL, 30)

In this sample, the player will skip the pre-roll, and will play the mid-roll only.

Note: This setting is strictly after - e.g. setting playAdsAfterTime to 15 will cause the player to ignore an ad break scheduled to play at 15s.

This option can be used also when player?.startPosition is set, which by default causes the player to skip the ads scheduled before the start time. Although, An application may want to force the player to play these ads. This can be achieved also by playAdsAfterTime parameter. For example:

Example : Ads are at 0, 15, 30, 60 and playAdsAfterTime = 40, player?.startPosition = 75 then 0 (preroll) and 60th second midroll will be played.

Live Streams

Only Preroll AdBreak can be configured for live medias and after the Ad playback, playback will go to the live edge.

With Live media(With/Without DVR), only AdBreakPositionType.EVERY can be configured for midrolls. It means play AdBreak at every n seconds (60 means on every 1 min ad will be played).

When we are playing on the live edge and an ad break starts, we have two options:

  1. Playback should be paused when ad break starts, and should resume from the same point it was paused when ad break ends.

  2. Playback should be paused when ad break starts, and should seek to live edge when ad break ends.

If Live media has DVR and returnToLive flag is true then after the Ad playback, player will go to the live edge. In case of Live media without DVR, player will always go to the live edge irrespective of returnToLive.

Because for Live Medias (With/Without DVR), we don’t have the player position hence we rely on timer which actually is hooked with the given frequency with AdBreakPositionType.EVERY. So please check the following scenario which should be taken count of,

Events

In addition to the current ad events (adbreakstart, adbreakend, adloaded etc.) we have added 2 new events:

AdEvent.adWaterFalling - Fired when an ad request failed and the player is trying to request the fallback. AdEvent.adWaterFallingFailed - Fired when the all fallback requests failed.

Note: AdEvent.error will not be fired with AdEvent.adWaterFalling but with AdEvent.adWaterFallingFailed.

Play Ad Now

All the above features are supported not only by AdvertisingConfig, but also by playAdNow api which gets an AdBreak as a parameter. The app may call it whenever it wants to play an AdBreak. It supports waterfalling and multiple AdPod playback.

To call this API get the AdvertisingController from player. Then call the playAdNow.

player?.advertisingController?.playAdNow(PLAY_AD_NOW_AD_BREAK)

var playAdNowAdBreak = AdBreak(AdBreakPositionType.POSITION, 15, listOf(listOf("AD_URL")))

player?.advertisingController?.playAdNow(playAdNowAdBreak)

For PlayAdNow’s AdBreak, AdBreakPositionType and position is irrelavant. App can pass anything non-null.