Server Side Ad Insertion using Google IMA

GoogleIMA

Supported Google IMA SDK version: 3.30.3

Specifications

1. Server-side ads insertion (SSAI) a.k.a Dynamic Ad Insertion (DAI) provides a combined video stream of ads and content (ads stitching), resulting in a seamless, broadcast-like viewing experience. QP Google IMA ads player supports:
2. Various ad formats, including standard linear and non-linear in-stream ads, interactive in-stream ads, and skippable ads.
3. Multiple ad placements: It can deliver pre-roll, mid-roll, and post-roll ads.
4. Can make ad requests to Google Ad Manager, the Google AdSense network, or any VAST-compliant ad server.
5. Replacement for all ad tag parameters used for the upcoming ad requests in a Live IMA DAI Streams.

Usage

This first step is the creation of an ad request for either the client-side ads insertion or server-side ads insertion. AdRequest instance is an object containing the data used to request ads from the server.

Create SSAI Ad Request for VOD stream

Create a VodSSAIAdsRequest ad request instance with contentSourceId and videoId properties as mandatory values.

Name	Type	Description
contentSourceId	String	specifies the stream request content source ID used for on-demand streams.
videoId	String	specifies the stream request video ID used for on-demand streams.

The following snippet shows ad request creation example:

val format: MediaType = MediaType.DASH
val contentSourceId = "2559737"
val videoId = "tos-dash"
val adRequest = VodSSAIAdsRequest(
  format = format,
  contentSourceId = contentSourceId,
  videoId = videoId
)

Create SSAI Ad Request for Live stream

Create a LiveSSAIAdsRequest ad request instance with assetKey property as a mandatory value.

Name	Type	Description
assetKey	String	specifies the stream request asset key used for live streams.

The following snippet shows ad request creation example:

val format: MediaType = MediaType.DASH
val assetKey = "sN_IYUG8STe1ZzhIIE_ksA"
val adRequest = LiveSSAIAdsRequest(
  format = format,
  assetKey = assetKey
)

Both VodSSAIAdsRequest and LiveSSAIAdsRequest also require that format property is provided as a mandatory value. The format of the stream request should be specified as either MediaType.DASH or MediaType.HLS format. Optionally each VodSSAIAdsRequest or LiveSSAIAdsRequest can be provided with adsId, apiKey, streamActivityMonitorId, adTagParameters, manifestSuffix, and contentUrl property values.

Name	Type	Description
adsId	String	specifies an opaque identifier for associated ad playback state, or null if assetKey (for live) or videoId(for VOD) should be used as the ads identifier.
apiKey	String	specifies the stream request API key. This is used for content authentication.
streamActivityMonitorId	String	specifies the ID for debugging the stream with the stream activity monitor. This is used to provide a convenient way to allow publishers to find a stream log in the stream activity monitor tool.
manifestSuffix	String	specifies the optional stream manifest's suffix, which will be appended to the stream manifest's URL. The provided string must be URL-encoded and must not include a leading question mark.
contentUrl	String	The url of the content to play.
adOverlayUIScopes	AdOverlayUIScope	The list of [AdOverlayUIScope] instances describing views that are on top of the ad view group.refer here.
loadMediaTimeoutMs	Int	specifies, in milliseconds, the ad media load timeout.
languageTag	String	specifies IETF BCP 47 language subtag string for the language used to display text for ads related labels such as a label indicating the total number of ads in a pod or a label indicating the click through URL etc.
adTagParameters	Map<String, String>	specifies a collection of extra parameters to pass to the ad server. When the video player requests a stream you have the ability to override certain parameters of the tag in your stream request. The only parameters that can be overridden are specified here: https://support.google.com/dfp_premium/answer/7320899 You can use the dai-ot and dai-ov parameters for stream variant preference: (See https://support.google.com/dfp_premium/answer/7320898 for more information).

note

Check the list of common primary language subtags at https://en.wikipedia.org/wiki/IETF_language_tag

Create Ad Composed Player

AdComposedPlayer manages both content and ad playback. It basically extends the conventional Player functionality and adds ads rendering to it.

// Create the content Player first
val contentPlayer = PlayerBuilder()
      .mediaURL("https://storage.googleapis.com/wvmedia/clear/h264/tears/tears.mpd")
      .mediaType(MediaType.DASH) // MediaType.HLS for HLS streaming
      .build(applicationContext)
// Wrap it up with and AdComposedPlayer, which will take care of Ad Loading and other Ad Management tasks.
val adsPlayer = with(contentPlayer) { player ->
    IMAAdsPlayerFactory.imaAdComposedPlayerWith(
      player,
      adRequest as SSAIAdsRequest
    )
  }

Replacement of all the ad tag parameters in a Live IMA DAI Stream.

You can change ad campaign targeting by replacing all the ad tag parameters used for the upcoming ad requests in a Live IMA DAI Streams.

// When new live program is about to be shown setup new ad campaign
val newAdTagParameters = MutableMap<String, String>()
// populate new ad tag parameters container
adsPlayer.replaceAdTagParameters(newAdTagParameters)

Listening to Ad Events

You can register AdEventListener instance with AdComposedPlayer for listening to Ad Events. The following ad events are triggered by AdEventListener callbacks:

1. Cue Point availability (available only after obtaining a response from Ad Server)
2. Ad Break Start called when the first Ad, in an Ad Break, have started playing. This event may also provide AdBreakInfo metadata for the active Ad Break.
3. Ad Start called when an Ad has started playing. This event will also provide AdInfo metadata for the active Ad.
4. Ad Playback Progress called during Ad Break playback when the Ad's progress is updated. This event will also provide AdProgressInfo metadata for the active Ad Break.
5. Ad End called when an Ad has finished playing. This event will also provide AdInfo metadata for the active Ad.
6. Ad Break End called when all the Ads, in an Ad Break, have finished playing. This event may also provide AdBreakInfo metadata for the active Ad Break.
7. Ad Error called when an error has been encountered during Ads playback. This event will also provide Error metadata for the active Ad.
8. Ad Tracking Event called when an ad tracking event sucha as ad's first quartile, midpoint, third quartile etc. is triggered. This event will also provide AdTrackingEvent metadata for the active Ad Break or Ad.

val adEventListener = object : AdEventListener {
      override fun onAdCuePointsAvailable(cuePoints: LongArray) {
        logger.info { "cue_points_available" }
      }
      override fun onAdBreakStart(adBreakInfo: AdBreakInfo?) {
        logger.info { "ad_break_start" }
      }
      override fun onAdStart(adInfo: AdInfo) {
        logger.info { "ad_start" }
      }
      override fun onAdEnd(adInfo: AdInfo) {
        logger.info { "ad_end" }
      }
      override fun onAdBreakEnd(adBreakInfo: AdBreakInfo?) {
        logger.info { "ad_break_end" }
      }
    }
adsPlayer.registerAdListener(adEventListener)