Skip to main content

Server Side Ad Insertion in Yospace player

The fl-ads-yospace library integrates with Yospace to offer Server Side Ad Insertion capability for both VOD and Live.

Setup

Yospace admanagement library must be loaded.

// Add the script tag for ad management library from yospace
<script type="text/javascript" src="admanagement-sdk-es5-3.1.3.min.js"></script>
note

Please use the Yospace library version shipped with the Quickplay libraries.

Wiring Authorization Response

Once an asset is authorized for Playback (refer Authorize Playback for an Asset), the authorization response indicates if the content is ad enabled. The Ad player must be setup only when this flag is enabled.

NameDescription
ssaiEnabledIndicates whether the content is Ad enabled

Playback with SSAI

Create AdSession

Create YospaceAdsSession by passing a reference to the YospaceAdManagement which is available when loading the yospace ad-management library.

const session =
flAdsYospace.YospaceAdsSessionFactory.createYospaceAdsSession(
YospaceAdManagement,
);

Initialize AdSession

The ad session can be initialized by passing the content url from authorization response and appropriate PlayerbackMode. The session once sucessfully initialized would return the actual playbackUrl to use.

PlaybackMode

The following playback modes are currently supported.

NameDescription
LiveRepresents Live mode
LiveRestartRepresents Live restart mode
LiveCatchupRepresents Live catchup mode
VodRepresents VOD mode
const adPlaybackUrl = await session.initialize({
contentURL: playbackAsset.contentUrl,
playbackMode: flAdsYospace.PlaybackMode.Vod,
});
note

For ad enabled contents (ssaiEnabled), the authorization service returns a VMAP playlist as contentUrl, but returns a regular manifest for Live Linear playback.

Create Content Player

Create a content player using the PlayerBuilder for Player or WebMAF Player. The .mediaUrl(..) should be the adPlaybackUrl received from ad session in the previous step.

const contentPlayer = playerBuilder
.mediaElement(videoElement)
.mediaUrl(adPlaybackUrl)
.drmLicenseUrl(playbackAsset.licenseUrl)
.drmScheme(playbackAsset.drmScheme)
.build();

Create Ad Player

The YospaceAdsPlayer is a composition on top of the regular content player and can be created as shown here.

// create a Yospace Ads player
const adPlayer = flAdsYospace.YospaceAdsPlayerFactory.createYospaceAdsPlayer(
contentPlayer,
session,
YospaceAdManagement,
);

This player could be used like conventional player from FLPlayer library for playback.

Listening to Ad Events

The player can subscribe to ad events to track the state of ad playback and implement custom UIs. The YospacePlayer emits the following ad events:

Event NameDescription
adbreakstartCalled when an ad break starts
adbreakendCalled when an ad break ends
adstartCalled when playback of an advert starts
adendCalled when playback of an advert ends
adcuepointsCalled when cue points are available
adprogressupdateCalled when an advert is playing
player.subscribe("adbreakstart", function (adBreakInfo) {
// update the player controls
}

player.subscribe("adprogressupdate", function (adInfo, progress) {
// update ad count down timer
});

Ad Metadata

AdBreakInfo

Represents an ad break object.

PropertyTypeDescription
adBreakIDstringUnique id of the ab break
contentTimePositionAdContentTimePositionThe position of the ad break, can be on of preroll, midroll or postroll
adBreakStartTimeOffsetMsnumberThe start position in milliseconds
remainingTimeMsnumberThe time remaining in the ad break from the playhead provided, in milliseconds
durationMsnumberThe duration of the ad break, in milliseconds
totalAdsnumberTotal number of adverts in the ad break
adBreakIndexnumberThe 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.
VASTProperties

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
adChoicesIconsArray 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.
fallbackImagesArray 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 subscription on Ad Player to listen to events that would provide ad vertification metadata which can be used for Open Measurement integration.

The subscription 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 listeners for the events

/**
* Called when the ad verification should be started.
* @param advert the advert.
* @param adVerifications The list of [AdVerification] instances.
*/
player.subscribe("adverificationstart", function (advert, adVerifications) {
// initialize the OM ad session and start ad verification.
}

/**
* Called when the ad verification should be completed.
*/
player.subscribe("adverificationend", function () {
// end ad verification and shutdown the OM ad session
});

/**
* Called when an ad tracking event is signalled.
* @param adTrackingEvent The [AdTrackingEvent] identifier.
*/

player.subscribe("adverttrackingevent", function (adTrackingEvent) {
// signal ad and media events
});

Verification Metadata

AdVerification

Represents an ad verification object.

PropertyTypeDescription
vendorKeyStringThe unique identifier of the verification provider
verificationParameterStringThe parameters which the verification provider script is expecting for the Ad Session
verificationResourceArray of VerificationResourceThe collection of VerificationResources
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
attributesDictionaryDictionary 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: