Verizon Media Ads

Verizon Media offers support for server-side ad-insertion (SSAI).

This article explains how to use the Verizon Media's Ads API exposed by THEOplayer to hook into these SSAI advertisements. Additionally, this API allows developers to manipulate the ad-related UX and UI.

SDKs

Web SDK	Android SDK	iOS SDK	tvOS SDK	Android TV SDK	Chromecast SDK	Roku SDK
Yes (2.63.0)	Yes (2.66.0)	Yes (2.65.0)	No	Yes (2.66.0)	No	Yes

Global Configuration

The examples below demonstrate how to pass along global configuration for the Verizon Media ads. These settings can be overwritten.

Web SDK

var player = new THEOplayer.Player(element, {
  verizonMedia: {
    defaultSkipOffset: 2, // Ad breaks added by SSAI are by default skippable after two seconds. Optional and defaults to unskippable.
    onSeekOverAd: "play-last" // When seeking over ad breaks, this configuration decides how to snapback and play any missed ad breaks.
    // Possible values are currently 'play-none', 'play-last' and 'play-all' where 'play-none' is the default.
  }
  // ... Other configuration goes here
});

Legacy Android SDK (4.12.x)

VerizonMediaConfiguration verizonMediaConfig = new VerizonMediaConfiguration.Builder()
                .defaultSkipOffset(5)
                .skippedAdStrategy(SkippedAdStrategy.PLAY_ALL) // When seeking over ad breaks, this configuration decides how to snapback and play any missed ad breaks.
                                                               // Possible values are currently 'play-none', 'play-last' and 'play-all' where 'play-none' is the default.
                .build();

THEOplayerConfig playerConfig = new THEOplayerConfig.Builder()
                .verizonMediaConfiguration(verizonMediaConfig)
                .build();

this.tpv = new THEOplayerView(Activity, playerConfig);

Legacy iOS/tvOS SDK (4.12.x)

let verizonMediaPlayerConf = VerizonMediaConfiguration(
            defaultSkipOffset: 5,
            onSeekOverAd: SkippedAdStrategy.PLAY_ALL) // When seeking over ad breaks, this configuration decides how to snapback and play any missed ad breaks.
                                                      // Possible values are currently 'play-none', 'play-last' and 'play-all' where 'play-none' is the default.

let playerConf = THEOplayerConfiguration(verizonMedia: verizonMediaPlayerConf)

let player = THEOplayer(configuration: playerConf)

Roku SDK

function Init()
  ...
    m.player = m.top.findNode("THEOPlayer")
    m.player.configuration = {
      "license": "" ' put the THEOplayer license between apostrophes,
      "verizonMedia" : {
		    "defaultSkipOffset": 5,
		    "onSeekOverAd": "play-last"
      }
    }
  ...
end function

Verizon Media Ads API

Specifying a source which contains server-side ads configured through the Verizon Media pre-integration will have the player expose an Ads API specific to Verizon Media.

Web SDK

Specifying a source which performs SSAI will have the player expose information about this SSAI on the player.verizonMedia.ads API:

• player.verizonMedia.ads.adBreaks: Specifies all ad breaks that are currently in the stream by using SSAI through Preplay.
• player.verizonMedia.ads.currentAdBreak: If applicable, returns the ad break that is currently being played.
• player.verizonMedia.ads.currentAds: If applicable, returns a list of the current ads being played.
• player.verizonMedia.ads.skip(): If there is an ad break playing, and it is skippable, skip the ad break to the next content (or next seek point in case of snapback)

Calling the vdms.ads.skip() function on a live stream will not have any effect.

In addition, event listeners are available to listen to new ad breaks:

For adbreaks there are the following events defined :

• adbreakbegin
• adbreakend
• adbreakskip
• addadbreak
• removeadbreak

For ads there are the following events defined :

• adbegin
• adchange
• adend
• adfirstquartile
• admidpoint
• adthirdquartile
• adcomplete

// Sample source snippet

player.verizonMedia.ads.adBreaks.addEventListener("addadbreak", (event) => {
  // do something with event.adBreak as it is an ad break added through SSAI, an example:
  const adBreak = event.adBreak;
  if (adBreak.duration <= 15) {
    adBreak.skipOffset = -1; // Do not allow skipping of short ad breaks
  } else if (adBreak.duration > 60) {
    adBreak.skipOffset = 10; // Allow skipping of long ad breaks after ten seconds
  } else {
    adBreak.skipOffset = 0; // For all other ad breaks, allow immediate skipping
  }
  // subscribe to additional events
  event.adBreak.addEventListener("adbreakbegin", console.log);
  event.adBreak.addEventListener("adbreakend", console.log);
  for (var i = 0; i < event.adBreak.ads.length; i++) {
    event.adBreak.ads[i].addEventListener("adbegin", console.log);
    event.adBreak.ads[i].addEventListener("adend", console.log);
  }
});

Android (TV) SDK

Specifying a source which performs SSAI will have the player expose information about this SSAI on the player.verizonMedia.ads API:

player.verizonMedia.ads.adBreaks: Specifies all ad breaks that are currently in the stream by using SSAI through Preplay. player.verizonMedia.ads.currentAdBreak: If applicable, returns the ad break that is currently being played. player.verizonMedia.ads.currentAds: If applicable, returns a list of the current ads being played. player.verizonMedia.ads.skip(): If there is an ad break playing, and it is skippable, skip the ad break to the next content (or next seek point in case of snapback) skip()

Calling the vdms.ads.skip() function on a live stream will not have any effect.

In addition, event listeners are available to listen for specific events:

On the ad break list the following listeners can be added:

• addadbreak
• removeadbreak

On an ad break the following listeners can be added:

• adbreakbegin
• adbreakend
• adbreakskip
• adbreakupdate

On the ad list inside an ad break the following listeners can be added:

• removead

On an individual ad the following listeners can be added:

• adbegin
• adend
• adfirstquartile
• admidpoint
• adthirdquartile
• adcomplete

EventListener<VerizonMediaAdEvent> adListener = (VerizonMediaAdEvent event) -> {
            // Do something with the ad
            event.getAd();
};

EventListener<VerizonMediaAdBreakEvent> adBreakListener = (VerizonMediaAdBreakEvent event) -> {
            // Do something with the adbreak
            event.getAdBreak();
};

EventListener<VerizonMediaAdBreakListEvent> adBreakListListener = (VerizonMediaAdBreakListEvent event) -> {
            // Do something with the adbreak
            event.getAdBreak().addEventListener(VerizonMediaAdBreakEventTypes.ADBREAK_BEGIN, adBreakListener);
            event.getAdBreak().addEventListener(VerizonMediaAdBreakEventTypes.ADBREAK_END, adBreakListener);

            Iterator<VerizonMediaAd> ads =  event.getAdBreak().getAds().iterator();
            while (ads.hasNext()) {
                ads.next().addEventListener(VerizonMediaAdEventTypes.AD_BEGIN, adListener);
            }
};

this.tpv.getPlayer().getVerizonMedia().getAds().getAdBreaks().addEventListener(VerizonMediaAdBreakListEventTypes.ADD_ADBREAK, adBreakListListener);

iOS (tvOS) SDK

Specifying a source which performs SSAI will have the player expose information about this SSAI on the player.verizonMedia.ads API:

player.verizonMedia.ads.adBreaks: Specifies all ad breaks that are currently in the stream by using SSAI through Preplay. player.verizonMedia.ads.currentAdBreak: If applicable, returns the ad break that is currently being played. player.verizonMedia.ads.currentAds: If applicable, returns a list of the current ads being played. player.verizonMedia.ads.skip(): If there is an ad break playing, and it is skippable, skip the ad break to the next content (or next seek point in case of snapback) skip()

Calling the vdms.ads.skip() function on a live stream will not have any effect.

In addition, event listeners are available to listen for specific events:

On the ad break list the following listeners can be added:

• addadbreak
• removeadbreak

On an ad break the following listeners can be added:

• adbreakbegin
• adbreakend
• adbreakskip
• adbreakupdate

On the ad list inside an ad break the following listeners can be added:

• removead

On an individual ad the following listeners can be added:

• adbegin
• adend
• adfirstquartile
• admidpoint
• adthirdquartile
• adcomplete

let adListener = { (event: VerizonMediaAdBeginEvent) in
            if let ad = event.ad {
                // do something with the ad.
            }
}

let adBreakBeginListener = { (event: VerizonMediaAdBreakBeginEvent) in
            if let adbreak = event.adBreak {
                // do something with the ad break.
            }
}

let adBreakArrayListener = { (event: VerizonMediaAddAdBreakEvent) in
            if let adbreak = event.adBreak {
                _ = adbreak.addEventListener(type: VerizonMediaAdBreakEventTypes.AD_BREAK_BEGIN, listener: adBreakBeginListener)
                _ = adbreak.ads.first?.addEventListener(type: VerizonMediaAdEventTypes.AD_BEGIN, listener: adListener)
            }
}

let adBreakArrayListenerRef = player.verizonMedia.ads.adBreaks.addEventListener(type: VerizonMediaAdBreakArrayEventTypes.ADD_AD_BREAK, listener: adBreakArrayListener)

Roku SDK

<?xml version="1.0" encoding="utf-8" ?>
<component name="TestScene" extends="Scene">
    <interface>
        <function name="callbackOnEventAddAdBreak"/>
    </interface>

    <script type = "text/brightscript" >

        <![CDATA[

        function Init()
            m.player = m.top.findNode("TestPlayer")
            m.player.configuration = {
              "license": "" ' put the THEOplayer license between apostrophes
            }
            m.player.callFunc("addEventListener", m.player.Event.addadbreak, "callbackOnEventAddAdBreak")

            setSource()
        end function

        function setSource()
	        ...
        end function

        function callbackOnEventAddAdBreak(eventData)
		    verizonMedia = m.player.verizonMedia

			' search in loop for currently added ad break
		    for each adBreak in verizonMedia.ads.adBreaks
		        if adBreak.startTime = eventData.adBreak.startTime
			        ' set proper skip offset time depending on ad break duration
		            if adBreak.duration <= 15
		                adBreak.skipOffset = -1
		            else if adBreak.duration > 60
		                adBreak.skipOffset = 10
		            else
		                adBreak.skipOffset = 0
		            end if
		        end if
		    end for

			' assigning whole object instead of changing value of field is required due to roku specific architecture
		    m.player.verizonMedia = verizonMedia

			' log data about all ads inside currently added ad break
		    for each ad in eventData.adBreak.ads
		        ? "adBegin : "; ad.startTime
		        ? "adEnd : "; ad.endTime
		    end for
        end function
        ]]>

    </script>

    <children>
        <THEOplayer id="TestPlayer"/>
    </children>
</component>

Related articles

• Verizon Media - Preplay
• Verizon Media - Ping