Server Side Ad Insertion using MediaTailor

MediaTailor Ads

The MediaTailor library provides seamless integration with AWS MediaTailor for server-side ad insertion (SSAI) in video streaming applications.

Setup

Wiring Authorization Response

Once an asset is authorized for Playback (refer Authorize Playback for an Asset), the authorization response indicates the ssaiAdProvider should be mediatailor, adtype be ssai andcustom field will have mtSessionUrl. The mediatailor ad player must be setup only when all of the metadata are available.

Name	Description
ssaiAdProvider	Indicates the ad provider
adtype	type of the ad being served either csai or ssai
mtSessionUrl	mediatailor session url to get content url and ad tracking url

Usage

This first step is the creation of a MediaTailor Manager instance that will be used to intialize the session to retrieve playback URL and ad tracking URL to create MediaTailor Ad player.

Create a Mediatailor Manager

const mediatailorSession = flAdsMediatailor.createMediaTailorSession();

Session creation

The initialize method orchestrates the MediaTailor session creation process

const mediaTailorSessionConfiguration: MediatailorSessionConfiguration = {
    adsParams: { customAd: "value1" },
    playerParams: { playerType: "web" },
    manifestParams: { format: "hls" },
    availSuppression: {
        mode: flAdsMediatailor.AvailSuppressionMode.BEHIND_LIVE_EDGE,
        value: "00:00:21",
     },
    adSignaling: true,
    originParams: {
        customOriginParam1: "value1",
        customOriginParam2: "value2",
        region: "us-east-1"
    },
    overlayAvails: flAdsMediatailor.OverlayAvailsMode.ON,
    reportingMode: flAdsMediatailor.ReportingMode.SERVER,

};

const mediatailorInitializationData: MediatailorInitializationData = {
  sessionUrl: playbackAsset.mtSessionUrl,
  fallbackUrl: playbackAsset.contentUrl,
  mediaTailorSessionConfiguration: mediaTailorSessionConfiguration,
  maxRetries: 1,
  connectionTimeoutInMS: 1000,
}

try {
  const mediatailorMetadata: MediatailorMetadata = await mediatailorSession.initialize(
    mediatailorInitializationData,
    palConfiguration,
  )
} catch (error: Error) {
  console.log('Mediatailor session failure', error)
}

MediatailorInitializationData

Name	Type	Optional	Description
sessionUrl	string	false	MediaTailor session url.
fallbackUrl	string	false	content url given by playback Authorization response in case of session failure
mediaTailorSessionConfiguration	MediaTailorSessionConfiguration	true	Ad targetting parameters.
maxRetries	number	true	Maxinum number of retries on network failures
connectionTimeoutInMS	number	true	Maximum amount of time (in milliseconds) to wait while trying to establish a connection before giving up.

MediatailorSessionConfiguration

Parameter	Type	Description
adsParams	Map<String, Any>?	Key-value pairs that MediaTailor can read and send to the ad server in all session requests
playerParams	Map<String, Any>?	Preceding configuration used for session initialization request that defines the player variables and their aliases.
manifestParams	Map<String, Any>?	Query parameters included in the parent manifest and tracking URLs in the response.
availSuppression	AvailSuppression	availSuppression
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.
originParams	Map<String, Any>?	custom origin parameters for the session.
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.
reportingMode	ReportingMode	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	ad break suppression
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

ReportingMode

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	string	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	number	Defines the length limit of the generated nonce.
omidPartnerName	number	The name of the partner integrating OMID measurement.
omidPartnerVersion	string	The version of the partner integrating OMID measurement.
omidVersion	string	The version of OMID that the player responsible for ad playback integrates with.
playerType	string	The partner provided player type.
playerVersion	string	The partner provided player version.
ppid	string	The publisher provided ID.
videoHeight	number	The height of the ad video element.
videoWidth	number	The width of the ad video element.

MediatailorMetadata

Name	Type	Optional	Description
manifestUrl	string	false	content url
status	string	false	Decribes session initialization status . sucsess or failure
reason	string	false	Detailed description on session status
trackingUrl	string	true	MediaTailor ad tracking url used to retrieve ad metadata

Create Ad Composed Player

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

const contentPlayer: Player = flPlayer
  .createPlayerBuilder()
  .mediaElement(mediaElement)
  .mediaUrl(mediatailorMetadata.manifestUrl)
  .mediaType(MediaType.HLS)
  .build();

const adsPlayer = mediatailorSession.createMediatailorPlayer(
    contentPlayer,
    logger,
    mediatailorMetadata?.trackingUrl
  );

Listening to Ad Events

To listen to ad events, subscribe to any of the following events adbreakstart, adbreakend, adstart or adend.

adsPlayer.subscribe('adbreakstart', (adBreakInfo: AdBreakInfo) => {
  console.log('Ad break started', adBreakInfo);
});

adsPlayer.subscribe('adstart', (adInfo: AdInfo) => {
  console.log('Ad started', adInfo);
});

adsPlayer.subscribe('adend', (adInfo: AdInfo) => {
  console.log('Ad ended', adInfo);
});

adsPlayer.subscribe('adbreakend', (adBreakInfo: AdBreakInfo) => {
  console.log('Ad break ended', adBreakInfo);
});