Skip to main content

Server Side Ad Insertion in Yospace player

Server Side Ad Insertion (SSAI) is the paradigm of stitching advertisements into the content directly on the server side. This allows for the same personalised ads experience with minimal complexity on the application side.

Setup

To employ the Quickplay SSAI solution using Yospace, the Yospace ad-management library must be loaded into the application.

// Add the gradle dependency for ad management library from Yospace with appropriate version in build.gradle
implementation 'com.yospace:admanagement-sdk:3.6.1'
note

This version is subject to change as the Quickplay libraries are updated. Please make sure that the version of Yospace ad management SDK is compatible with the Quickplay libraries that you are using.

Prerequisites

If the playback asset is eligible for SSAI, it is indicated to the application when authorizing it for playback with the Quickplay platform, using ContentAuthorizationToken.ssaiEnabled.
All SSAI related functionality must be set up only when this flag is enabled.

// obtain ContentAuthorizationToken when `ContentAuthorizer.authorizePlayback` is successful
if (contentAuthorizationToken.ssaiEnabled == true) {
// setup yospace and build Yospace player for SSAI playback
} else {
// build player using `PlayerBuilder.build` for normal playback
}

Playback with SSAI

Adhering to the following steps in the mentioned order will ensure the seamless integration of SSAI functionality into the application.

1. Create YospaceSessionInitializationData

YospaceSessionInitializationData encapsulates all the information required to initialise SSAI. The initialization data can be created by passing the content URL from authorization response i.e. ContentAuthorizationToken.contentURL and the appropriate YospaceAdsSession.PlaybackMode. It can also be used to customise other functionalities related to SSAI.

PropertyTypeDefault ValueDescription
contentURLString-The url of the content to play.
playbackModeYospaceAdsSession.PlaybackMode-Indicates whether the playback is live or VOD.
isValidationRequiredBooleanfalseThe flag indicating if Session state validation is required. This flag should be set to [Boolean.true] only when performing Yospace Validation Tests.
keepProxyAliveBooleantrueThe property that controls if Yospace proxy session should be kept alive or not.
connectTimeoutMsInt5000The timeout used when establishing an HTTP connection for session initialisation and for CSM polling, in milliseconds.
resourceTimeoutMsInt5000The timeout used when firing analytic beacons and pre-fetching VAST resources, in milliseconds.
userAgentString"" (Empty string)The user agent to use when firing Yospace analytic tracking Beacons.
info

For playbacks in Live or Restart mode, use YospaceAdsSession.PlaybackMode.Live. For catchup and VOD playbacks, use YospaceAdsSession.PlaybackMode.Vod.

val yospaceSessionInitializationData = YospaceSessionInitializationData (
contentAuthorizationToken.contentURL,
yospacePlaybackMode // pass Live for live / restart playbacks, and Vod for catchup / VOD playbacks.
)

2. Create YospaceAdsSession

Using YospaceSessionInitializationData customized in the previous step, create YospaceAdsSession that allows the applications to open an appropriate playback session with Yospace.

val yospaceAdsSession = YospaceAdsPlayerFactory.createYospaceAdsSession(yospaceSessionInitializationData)

3. Initialize YospaceAdsSession

Depending on the playback mode, YospaceAdsSession offers different methods according to the type of playback to obtain the playback URL that can be used to build the player.
Use YospaceAdsSession.initializeLiveSession for Live / Restart playbacks and YospaceAdsSession.initializeVODSession for Catchup / VOD playbacks.

note

If the Yospace session initialisation fails, the application can still use the URL obtained during authorization (that was passed to the SDK in Step 1) to continue with a normal playback without SSAI.

// use below snippet for live / restart playbacks. 
yospaceAdsSession.initializeLiveSession() { sessionInitResult ->
when (sessionInitResult) {
is Result.Success -> {
val playbackURL = sessionInitResult.value
// use playbackURL to create the player
}
is Result.Failure -> {
val error = sessionInitResult.value
logger.trace { error.toString() }
// handle the error as required
// OR
// use the content URL obtained from ContentAuthorizationToken
// to continue playback without SSAI

}
}
}

// use below snippet for catchup / VOD playbacks.
yospaceAdsSession.initializeVODSession() { sessionInitResult ->
when (sessionInitResult) {
is Result.Success -> {
val playbackURL = sessionInitResult.value
// use playbackURL to create the player
}
is Result.Failure -> {
val error = sessionInitResult.value
logger.trace { error.toString() }
// handle the error as required
// OR
// use the content URL obtained from ContentAuthorizationToken
// to continue playback without SSAI

}
}
}

4. Create Player

Using the playback URL received from YospaceAdsSession in the previous step, create a normal player using PlayerBuilder to obtain the Quickplay Player.

val player = PlayerBuilder()
.mediaURL(contentUrl)
.mediaType(MediaType.DASH)
.drmScheme(DRMScheme.NONE)
.drmLicenseURL("")
.build(applicationContext)

5. Create YospaceAdsPlayer

YospaceAdsPlayer is an implementation of Player that holds additional functionality to support SSAI. Use YospaceAdsPlayerFactory to create this player according to the playback type.

// create YospaceAdsPlayer for Live / Restart playbacks
val yospaceAdsPlayer = YospaceAdsPlayerFactory.createYospaceLiveSessionAdsPlayer(
player,
yospaceAdsSession
)

// create YospaceAdsPlayer for Catchup / VOD playbacks
val yospaceAdsPlayer = YospaceAdsPlayerFactory.createYospaceVODSessionAdsPlayer(
player,
yospaceAdsSession
)

Listening to Ad Events

Attach listeners

An AdEventListener and a YospaceAdsPlayer.Listener can be attached to the Yospace player to allow listening for all notable events.

// create listeners
val myAdEventListener = object: AdEventListener {
// implement AdEventListener to listen to ad events
}

val yospaceListener = object: YospaceAdsPlayer.Listener {
//Implement YospaceAdsPlayer.Listener to listen to yospace session related events
}

//Listening to Ad Events
yospaceAdsPlayer.adEventListener = myAdEventListener
//Listening to Yospace Session Timeout
yospaceAdsPlayer.addYospaceListener(yospaceListener)

Listening to Ad Events

The player can attach an AdEventListener to the YospaceAdsSession to track the state of ad playback and implement custom UIs.

  //Called when cue points are available.
fun onAdCuePointsAvailable(cuePoints: LongArray)

//Called when an Ad started playing.
fun onAdStart(adInfo: AdInfo)

//Called when an Ad finished playing.
fun onAdEnd(adInfo: AdInfo)

//Called when the first Ad, in an Ad-Break, have started playing. Use this to make any corresponding UI changes, such as player controls.
fun onAdBreakStart(adBreakInfo: AdBreakInfo?)

//Called when all the Ads, in an Ad-Break, have finished playing. Use this to make any corresponding UI changes, such as player controls.
fun onAdBreakEnd(adBreakInfo: AdBreakInfo?)

//Called when an error has been encountered during Ads playback.
fun onAdError(error: Error)

Handling Yospace Session Timeout

The Yospace player can attach a YospaceAdsPlayer.Listener to YospaceAdsPlayer to listen when a Yospace session might have timed out.

  /**
* Called when Yospace Session times out, after approximately 2 minutes,
* if the stream manifest is not requested in that time. This may happen when the client application
* streams Live SSAI enabled content and goes into background and remains in that state for at least 2 minutes.
*/
fun onLivePlaybackSessionTimeout()

When this method is triggered, the application should stop the player and re-initialise the playback session with a new player instance.

Flow of events to re-initialize the player:
  • Dispose the video renderer using Player.detachRendererView by passing the player's parent view.
  • Stop the existing player.
  • Reset the player controls and Ad views.
  • Authorize the playback again.
  • Use the new information from the new ContentAuthorizationToken to create a new Player.
  • Replace the player variable with the new player.
  • Attach listeners and set the player controls to the new player.
  • Start the playback.

Ad Metadata

AdBreakInfo

Represents an ad break object.

PropertyTypeDescription
adBreakIDStringUnique id of the ad break
contentTimePositionAdContentTimePositionThe position of the ad break, can be on of preroll, midroll or postroll
adSequencePositionIntThe sequence position of the ad within the ad break.
adBreakStartTimeOffsetMsDoubleThe content time offset at which the current ad break was scheduled
remainingTimeMsDoubleThe natural playback time remaining for the ad break in milliseconds
durationMsDoubleThe maximum duration of the ad break in milliseconds.
totalAdsIntThe total number of ads contained within this ad break.
adBreakIndexIntThe index of the current ad break

AdInfo

Represents an advert object.

PropertyTypeDescription
adIDstringThe identifier of the advert
sequencenumberThe sequence of the advert
adStartTimeOffsetMsnumberThe start playhead position of the advert in milliseconds
durationMsnumberThe duration of the advert in milliseconds
remainingTimeMsnumberReturns the natural playback time remaining for the advert in milliseconds
isSkippablebooleanIndicates if the ad is skippable
skipOffsetMsnumberThe 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.
isFillerbooleanWhether this advert represents filler content
adBreakInfoAdBreakInfoThe ad break in which the advert belongs in
adVastPropertiesAdVastPropertiesRepresents a VAST properties of this advert.
AdVASTProperties

Represents a VAST properties object.

PropertyTypeDescription
adSystemstringThe source ad server of the advert
adTitlestringThe common name of the advert
adServingIdstringAn identifier used to compare impression-level data across systems
adIdstringThe Ad identifier of the creative
creativeIdstringThe identifier of the creative
categorystringCategory of the advert content
descriptionstringThe longer description of the advert
advertiserstringAdvertiser name
pricingstringPricing element of the advert
surveystringAn URI to any resource file having to do with collecting survey data
expiresstringNumber of seconds in which the ad is valid for execution
adChoicesIconsCollection of AdChoicesIconThe List of AdChoicesIcon instances
AdChoicesIcon

Represents VAST response metadata related to WTA (Why This Ad?) privacy disclosures. These disclosures are returned inside the AdChoices element of the VAST response. WTA related attributes are part of the relevant Icon tag and are used to render the AdChoices icon.

PropertyTypeDescription
programstringThe program represented in the icon (e.g. AdChoices).
widthstringThe pixel width of the icon asset.
heightstringThe pixel height of the icon asset.
xPositionstringThe x-coordinate of the top, left corner of the icon asset relative to the ad display area. Values of "left" or "right" also accepted and indicate the leftmost or rightmost available position.
yPositionstringThe y-coordinate of the top left corner of the icon asset relative to the ad display area; values of"top" or "bottom" also accepted.
offsetstringThe time of delay from when the associated linear creative begins playing to when the icon should be displayed; provided in the format HH:MM:SS.mmm or HH:MM:SS where .mmm is milliseconds (optional).
durationstringThe duration icon should be displayed unless clicked or ad is finished playing; provided in the format HH:MM:SS.mmm or HH:MM:SS where .mmm is milliseconds (optional).
apiFrameworkstringIdentifies the API needed to execute the icon resource file if applicable.
altTextstringThe alternative text for the image. In an html5 image tag this should be the text for the alt attribute. This should enable screen readers to properly read back a description of the icon for visually impaired users.
imageURLstringThe URL of the image file for the icon (PNG is preferred).
clickThroughURLstringThe URL of the action that occurs when a user clicks the AdChoices icon. In most cases,the user sees the Ad Settings page that the media player opens when the icon is clicked.
fallbackImagesCollection of IconClickFallbackImageThe List of IconClickFallbackImage instances.
IconClickFallbackImage

In cases where the WTA icon can not display the Ad Settings page, such as when the platform does not support a browser, WTA can show users a fallback image that contains the same disclosure information as the Ad Settings page. When an icon click occurs, the ad must pause and the image must be rendered above the video. The player must provide a means for the user to close the dialogue, for example by pressing the back button. The image must not be obstructed and should not be downloaded unless a click-action occurs.

PropertyTypeDescription
widthstringThe pixel width of the image asset.
heightstringThe pixel height of the image asset.
altTextstringThe alternative text for the fallback image.
imageURLstringThe URL of the image file for the fallback image (PNG is preferred).

Open Measurement

The client can set open measurement event delegate on Ad Player to listen to events that would provide ad vertification metadata which can be used for Open Measurement integration.

The delegate only provides metadata and resources for open measurement and the client must integrate open measurement on the app. Please refer IAB Open Measurement for complete integration of Open Measurement SDK.

The following are the delegate methods

/**
* Called when the ad verification should be started.
*
* @param adVerifications The list of [AdVerification] instances.
* @param vastProperties The [VASTProperties] instance.
* @param adVideoProperties The [AdVideoProperties] instance.
*/
fun onAdVerificationStart(
adVerifications: List<AdVerification>,
vastProperties: VASTProperties,
adVideoProperties: AdVideoProperties
)

/**
* Called when the ad verification should be completed.
*/
fun onAdVerificationEnd()

/**
* Called when an ad tracking event is signalled.
*
* @param adTrackingEvent The [AdTrackingEvent] identifier.
*/
fun onAdTrackingEvent(adTrackingEvent: AdTrackingEvent)

Verification Metadata

AdVerification

Represents an ad verification object.

PropertyTypeDescription
vendorKeyStringThe unique identifier of the verification provider
verificationParametersString?The parameters which the verification provider script is expecting for the Ad Session.
verificationResourcesList<VerificationResource>The list of VerificationResource objects.
VerificationResource

Represents an ad verification resource object.

PropertyTypeDescription
nameStringThe name of the node for the ad verification resource
valueStringThe value of the node for the ad verification resource
attributesMap<String, String>The Map instance of attributes of the node for the ad verification resource.

For example, lets say the ad response has the following ad verification metadata :

  <AdVerifications>
<Verification vendor=“iabtechlab.com-omid”>
<JavaScriptResource apiFramework=“omid” browserOptional=“true”>
<![CDATA[https://server.com/omid-validation-verification-script-v1.js]]>
</JavaScriptResource>
<VerificationParameters>
<![CDATA[parameterstring]]>
</VerificationParameters>
</Verification>
</AdVerifications>

In the example above: