Server Side Ad Insertion using FLMediaTailor

The fl-player-ads-mediatailor library enables the playback of AWS Elemental MediaTailor curated streams with advertisements. To build a MediaTailor player, use the MediaTailorAdsPlayerBuilder API with the following property's:

Property	Type	Description
sessionURL	String	Sets the URL to create remote session with AWS Elemental MediaTailor.
contentURL	String	Sets the fallback URL to content playback when MediaTailor session fails.
sessionConfiguration	SessionConfiguration	Session configuration parameters to create AWS MediaTailor session.
adPlaybackPolicy	AdPlaybackPolicy	Sets the [AdPlaybackPolicy] instance that specifies the policy rules for MediaTailor ads handling.
playbackPolicyHandler	PlaybackPolicyHandler	Sets the [PlaybackPolicyHandler] instance that enforces the policy rules related to the content with MediaTailor ads.
playbackPolicyHandlerListener	PlaybackPolicyHandler.Listener	Sets the [PlaybackPolicyHandler.Listener] instance that provides the notification for ad playback policy related events.
palConfiguration	PALConfiguration	Sets the [PALConfiguration] instance that is used in the [PALSession] initialization. Optionally sets the permission to store user data like cookies, device IDs, and advertising IDs when using [PALSession] calls.
allowPALSessionDataStorage	Boolean	If the value is [Boolean.true] the user gives the consent to store data.The default value is [Boolean.false] - no consent.
httpClientConfig	HttpClientConfiguration	The Http Client configuration details for MediaTailor API calls.

SessionConfiguration

Parameter	Type	Description
adsParams	Map<String, String>	Key-value pairs that MediaTailor can read and send to the ad server in all session requests.
playerParams	Map<String, String>	Preceding configuration used for session initialization request that defines the player variables and their aliases.
originParams	Map<String, Any>	Custom origin parameters for the session.
manifestParams	Map<String, String>	Query parameters included in the parent manifest and tracking URLs in the response.
overlayAvails	OverlayAvailsMode	MediaTailor support for overlay ads is enabled by default. A specific SCTE-35 ad-marker type in the manifest triggers the insertion of an overlay ad. Because some players might not support client-side rendering of overlay ads, you can disable the feature at the session level.
availSuppression	AvailSuppression	The MediaTailor avail suppression configuration.
adSignaling	Boolean	To enable ad ID signaling, add an adSignaling object as a top level object, and inside, add a parameter called enabled and value of true. The default adSignaling value is disabled.
reportingMode	SessionReportingMode	MediaTailor supports a hybrid mode for session tracking. In this mode, the service emits playback-related ad-tracking events, but makes the complete client-side tracking payload available for the session.

AvailSuppression

Parameter	Type	Description
mode	AvailSuppressionMode	The avail suppression mode.
value	String	A time relative to the live edge in a live stream.

AvailSuppressionMode

Parameter	Description
OFF	Ad suppression is OFF
BEHIND_LIVE_EDGE	When set to BEHIND_LIVE_EDGE, MediaTailor doesn't fill ad breaks on or behind the aws.availSuppressionValue time
AFTER_LIVE_EDGE_FULL_AVAIL_ONLY	MediaTailor doesn't fill ad breaks on or behind the avail suppression period and full avail suppression policy
AFTER_LIVE_EDGE_PARTIAL_AVAIL	MediaTailor doesn't fill ad breaks on or behind the avail suppression period and invoke partial ad break fills when and session starts mid-break

OverlayAvailsMode

Parameter	Description
ON	Enabling overlaying ads.
OFF	Disabling overlaying ads.

SessionReportingMode

Parameter	Description
SERVER	MediaTailor supports a hybrid mode for session tracking. In this mode, the service emits playback-related ad-tracking events, but makes the complete client-side tracking payload available for the session.

PALConfiguration

Property	Type	Description
willAdAutoPlay	Boolean	Defines whether the ad will be auto played without waiting for user interaction or not.
willAdPlayMuted	Boolean	Defines whether the ad will be played while muted or not.
continuousPlayback	Boolean	Defines whether the player intends to continuously play the content videos one after another similar to TV broadcast or video playlist.
descriptionUrl	URL	Defines the description URL of the content during which the ad will be played.
iconsSupported	Boolean	Defines whether VAST icons are supported by the video player.
nonceLengthLimit	Int	Defines the length limit of the generated nonce.
omidPartnerName	String	The name of the partner integrating OMID measurement.
omidPartnerVersion	String	The version of the partner integrating OMID measurement.
playerType	String	The partner provided player type.
playerVersion	String	The partner provided player version.
ppid	String	The publisher provided ID.
videoHeight	Int	The height of the ad video element.
videoWidth	Int	The width of the ad video element.

note

The client application may optionally provide custom AdPlaybackPolicy, and PlaybackPolicyHandler implementation, and also PALConfiguration instance as MediaTailorAdsPlayerBuilder properties.

MediaTailor Player Creation Use Cases

The following use cases are supported by MediaTailorAdsPlayerBuilder for MediaTailorPlayer instance creation:

1. The application provides session URL, content URL and PAL configuration and optionally other builder properties.
2. The application provides session URL, content URL and optionally other builder properties but not PAL configuration.
3. The application provides content URL and PAL configuration and optionally other builder properties but not session URL.
4. The application provides content URL and optionally other builder properties but not session URL and PAL configuration.

Create MediaTailor Player

A Player should be built using MediaTailorAdsPlayerBuilder as an extension of PlayerBuilder (see MediaTailor Player Creation Use Cases section). Here is a typical setup for building the player:

import com.quickplay.vstb7.player.model.MediaType

val mediaTailorAdsPlayerBuilder = MediaTailorAdsPlayerBuilder()
mediaTailorAdsPlayerBuilder.mediaType(MediaType.DASH)
mediaTailorAdsPlayerBuilder.contentURL(contentURL)
mediaTailorAdsPlayerBuilder.sessionURL(sessionURL)
val sessionConfiguration = SessionConfiguration.Builder().apply {
   adsParams(
      mapOf(
         "assetid" to "test1",
         "podduration" to "15"
      )
   )
   playerParams(
      mapOf(
         "deviceType" to "androidmobile",
         "uid" to "test-uid-12345",
      )
   )
   originParams(
      mapOf(
         "origin1" to "androidmobile",
         "origin2" to "xjhhddli-9189901-uic"
      )
   )
   manifestParams(
      mapOf(
         "deviceType" to "androidmobile",
         "uid" to "test-uid-12345",
      )
   )
   overlayAvails(OverlayAvailsMode.OFF)
   availSuppression(
      AvailSuppression(AvailSuppressionMode.AFTER_LIVE_EDGE_FULL_AVAIL_ONLY, value = "00:05:00")
   )
   adSignaling(false)
}.build()
mediaTailorAdsPlayerBuilder.sessionConfiguration(sessionConfiguration)
mediaTailorAdsPlayerBuilder.httpClientConfig(
   HttpClientConfiguration(
      connectionTimeout = 8,
      readTimeout = 8,
      userAgent = null,
      retryOnNetworkFailure = true,
      maxNetworkFailureRetryCount = 2,
      baseNetworkFailureRetryDelayMs = 2000,
      applicationInterceptors = emptyList()
   )
)
mediaTailorAdsPlayerBuilder.playbackPolicyHandlerListener(stateObserver)
coroutineScope.launch {
   when (val result: Result<MediaTailorPlayer?, Error?> =
      mediaTailorAdsPlayerBuilder.buildAsync(
         context
      )
   ) {
      is Result.Success -> {
         val mediaTailorPlayer = result.value
         mediaTailorPlayer?.let {
            it.addListener(stateObserver)
            it.addAuxiliaryListener(stateObserver)
            it.addListener(internalPlayerListener)
            it.registerAdListener(stateObserver)
            player = composablePlayerWith(it as Player)
         }
      }

      is Result.Failure -> {
         // handle error
      }
   }
}

note

NOTE that the PlayerBuilder build function is deprecated and MUST not be used and only buildAsync should be used. This function is declared assuspendfunction and MUST be called using CoroutineScope builder function e.g. using launch extension function.

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 onAdPlaybackProgress(adProgresInfo: AdProgressInfo) {
        logger.info { "ad_progress" }
      }
      override fun onAdEnd(adInfo: AdInfo) {
        logger.info { "ad_end" }
      }
      override fun onAdBreakEnd(adBreakInfo: AdBreakInfo?) {
        logger.info { "ad_break_end" }
      }
    }
adsPlayer.registerAdListener(adEventListener)

Ad Metadata

AdInfo

Represents an advert object.

Property	Type	Description
adID	string	The identifier of the advert
sequence	number	The sequence of the advert
adStartTimeOffsetMs	number	The start playhead position of the advert in milliseconds
durationMs	number	The duration of the advert in milliseconds
remainingTimeMs	number	Returns the natural playback time remaining for the advert in milliseconds
isSkippable	boolean	Indicates if the ad is skippable
skipOffsetMs	number	The value of skip offset for the advert, in milliseconds. If the VAST skip offset is not defined then this method returns -1, signifying that the advert cannot be skipped.
isFiller	boolean	Whether this advert represents filler content
adBreakInfo	AdBreakInfo	The ad break in which the advert belongs in
adVastProperties	AdVastProperties	Represents a VAST properties of this advert.

AdBreakInfo

Represents an ad break object.

Property	Type	Description
adBreakID	String	Unique id of the ad break
contentTimePosition	AdContentTimePosition	The position of the ad break, can be on of preroll, midroll or postroll
adSequencePosition	Int	The sequence position of the ad within the ad break.
adBreakStartTimeOffsetMs	Double	The content time offset at which the current ad break was scheduled
remainingTimeMs	Double	The natural playback time remaining for the ad break in milliseconds
durationMs	Double	The maximum duration of the ad break in milliseconds.
totalAds	Int	The total number of ads contained within this ad break.
adBreakIndex	Int	The index of the current ad break

note

The totalAds read from AdPlayer may not be accurate when it comes from onAdStart event. This may change once ad playback starts. GoogleIMA advises to read totalAds on or after FIRST_QUARTILE ad tracking event, to get a reliable data.