Server Side Ad Insertion

The FLAdvertisingYospace library integrates with Yospace to offer Server Side Ad Insertion capability for both VOD and Live.

Setup

Yospace AdManagement framework must be embedded with app.

note

Please use the Yospace framework 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

Create YoAdSession

Create a YoSessionInitData initialization data with content url, playback mode. Create YoAdSession using the init data created.

let initData = FLAdvertisingYospaceFactory.yoSessionInitData(contentUrl: contentUrl, playbackMode: .live)
// create ad session
let yoAdSession = FLAdvertisingYospaceFactory.adSession(initData: initData)

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

Initialize YoAdSession

Initialize the session to obtain playback url from the ad session instance. The session once sucessfully initialized would return the actual playbackUrl to use.

// initialize ad session with callback to handle session result
yoAdSession.initialize { result in
    switch result {
    case let .success(playbackUrl):
        // create ad player for playback
    case let .failure(error):
        // handle error
    }
}

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 and Ad Player

Create a player using the playback url received on session initialisation. Create the ad Player using main content Player and YoAdSession.

// create player using the playback url obtained from ad session initialisation
if let playbackURL = URL(string: playbackUrl) {
    let avURLAsset = AVURLAsset(url: playbackURL)
    let player = FLPlatformPlayerFactory.player(asset: avURLAsset)
    // Create ad player with player and ad session
    let adPlayer = FLAdvertisingYospaceFactory.adPlayer(player: player, yoAdSession: yoAdSession)
}

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

Listening to Ad Delegate Methods

The client can set delegate on ad player and listen to ad events to track the state of ad playback and implement custom UIs. The AdPlayer invokes the following ad delegate methods:

/// Called on ad playback failure
func adPlayer(ad: Ad?, didFailWith error: Error)

/// Called when cue points are available
func adPlayerDidProvide(cuepoints: [Int])

/// Called on ad break start
func adPlayerDidStart(adBreak: AdBreak)

/// Called on ad start
func adPlayerDidStart(ad: Ad)

/// Called on ad playback progress change
func adPlayer(ad: Ad?, didChange progress: TimeInterval)

/// Called on ad playback buffer state change
func adPlayer(ad: Ad?, didChangeBuffer isBuffering: Bool)

/// Called on occurance of ad track event
func adPlayer(ad: Ad?, didTrack event: AdTrackingEvent)

/// Called on ad end
func adPlayerDidEnd(ad: Ad)

/// Called on ad break end
func adPlayerDidEnd(adBreak: AdBreak)

Ad Metadata

AdBreak

Represents an ad break object.

Property	Type	Description
position	AdPosition	The position of the ad break, can be on of preroll, midroll or postroll
startTime	TimeInterval	The start position in seconds
duration	TimeInterval	The duration of the ad break, in seconds
totalAds	Int	Total number of adverts in the ad break

Ad

Represents an advert object.

Property	Type	Description
adId	String	The identifier of the advert
sequence	Int	The sequence of the advert
duration	TimeInterval	The duration of the advert in seconds
isSkippable	Bool	Indicates if the ad is skippable
adBreak	AdBreak	The ad break which the advert belongs to

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 integtration of Open Measurement SDK.

The following are the delegate methods

/// Called when the ad verification should be started.
/// - Parameters:
///   - adVerification: The list of `AdVerification` instances.
///   - vastProperties: The `VASTProperties` instance.
///   - adVideoProperties: The `AdVideoProperties` instance.
func adVerificationDidStart(adVerification: [AdVerification]?, vastProperties: VASTProperties, adVideoProperties: AdVideoProperties)

/// Called when the ad verification should be completed.
func adVerificationDidEnd()

/// Called when an ad tracking event is signalled.
/// - Parameter adTrackingEvent: The `AdTrackingEvent` identifier.
func adDidTrackEvent(event: AdTrackingEvent)

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”

VASTProperties

Represents a VAST properties object.

Property	Type	Description
skipOffset	TimeInterval	The number of seconds before the skip button is presented
isAutoPlay	Bool	Whether the player will auto-play content
adPosition	AdPosition	The position of the ad break, can be on of preroll, midroll or postroll
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
creativeId	String	CreativeId of the advert
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
industryIcons	Array of IndustryIcon	The list of IndustryIcon instances
extensions	Extensions	The custom VAST extensions properties

IndustryIcon

This part of the VAST response contains information about industry icons. Encapsulates the data from the <Icon> element of a VAST document. It is a graphic that overlays a small portion of the advert's video and is sometimes clickable.

Property	Type	Description
program	String	The program represented in the icon (e.g. "AdChoice, IndustryIcon")
width	String	The width of the icon asset
height	String	The 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
yPosition	String	The y-coordinate of the top left corner of the icon asset relative to the ad display area
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
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
apiFramework	String	The apiFramework 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 IndustryIcon 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

Represents the fallback image attributes.

Property	Type	Description
width	String	The width of the image asset
height	String	The width 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)