Server Side Ad Insertion

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.

Name	Description
ssaiEnabled	Indicates 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.

Name	Description
Live	Represents Live mode
LiveRestart	Represents Live restart mode
LiveCatchup	Represents Live catchup mode
Vod	Represents 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 Name	Description
adbreakstart	Called when an ad break starts
adbreakend	Called when an ad break ends
adstart	Called when playback of an advert starts
adend	Called when playback of an advert ends
adcuepoints	Called when cue points are available
adprogressupdate	Called 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.

Property	Type	Description
adBreakID	string	Unique id of the ab break
contentTimePosition	AdContentTimePosition	The position of the ad break, can be on of preroll, midroll or postroll
adBreakStartTimeOffsetMs	number	The start position in milliseconds
remainingTimeMs	number	The time remaining in the ad break from the playhead provided, in milliseconds
durationMs	number	The duration of the ad break, in milliseconds
totalAds	number	Total number of adverts in the ad break
adBreakIndex	number	The index of the current ad break

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.

VASTProperties

Represents a VAST properties object.

Property	Type	Description
adSystem	string	The source ad server of the advert
adTitle	string	The common name of the advert
adServingId	string	An identifier used to compare impression-level data across systems
adId	string	The Ad identifier of the creative
creativeId	string	The identifier of the creative
category	string	Category of the advert content
description	string	The longer description of the advert
advertiser	string	Advertiser name
pricing	string	Pricing element of the advert
survey	string	An URI to any resource file having to do with collecting survey data
expires	string	Number of seconds in which the ad is valid for execution
adChoicesIcons	Array of AdChoicesIcon	The 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.

Property	Type	Description
program	string	The program represented in the icon (e.g. AdChoices).
width	string	The pixel width of the icon asset.
height	string	The pixel height of the icon asset.
xPosition	string	The 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.
yPosition	string	The y-coordinate of the top left corner of the icon asset relative to the ad display area; values of"top" or "bottom" also accepted.
offset	string	The 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).
duration	string	The 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).
apiFramework	string	Identifies the API needed to execute the icon resource file if applicable.
altText	string	The 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.
imageURL	string	The URL of the image file for the icon (PNG is preferred).
clickThroughURL	string	The 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.
fallbackImages	Array of IconClickFallbackImage	The 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.

Property	Type	Description
width	string	The pixel width of the image asset.
height	string	The pixel height of the image asset.
altText	string	The alternative text for the fallback image.
imageURL	string	The 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.

Property	Type	Description
vendorKey	String	The unique identifier of the verification provider
verificationParameter	String	The parameters which the verification provider script is expecting for the Ad Session
verificationResource	Array of VerificationResource	The collection of VerificationResources

VerificationResource

Represents an ad verification resource object.

Property	Type	Description
name	String	The name of the node for the ad verification resource
value	String	The value of the node for the ad verification resource
attributes	Dictionary	Dictionary 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:

• the name of the ad verification resource is "JavaScriptResource"
• the value of the ad verification resource is: "https://server.com/omid-validation-verification-script-v1.js"
• the attributes of the ad verification resource are: apiFramework=“omid” and browserOptional=“true”