Server Side Ad Insertion in FLAdvertisingMediatailor

Overview

FLAdvertisingMediatailor is a comprehensive iOS SDK that integrates with AWS MediaTailor to provide server-side ad insertion (SSAI) capabilities. It supports both Video on Demand (VOD) and Live streaming content with seamless ad playback, advanced session configuration, tracking, and reporting.

Key Features

Server-side ad insertion for VOD and Live content
AWS MediaTailor integration
Customizable ad playback policies
Google PAL (Publisher Advertiser Library) support
Real-time ad event tracking and delegation
Configurable session parameters

Getting Started

Basic VOD Playback

import FLAdvertisingMediatailor

let contentUrl = URL(string: "https://example.com/vod.m3u8")!
let initialSessionUrl = "https://your-mediatailor-session-url"

let builder = FLMediatailorFactory.createPlayerBuilder(
    contentUrl: contentUrl,
    initialSessionUrl: initialSessionUrl,
    contentType: .vod
)

builder.build { adPlayer in
    // Use your configured VOD AdPlayer instance
    // Set delegate to receive ad events
    adPlayer.adDelegate = self
}

Basic Live Playback

import FLAdvertisingMediatailor

let contentUrl = URL(string: "https://example.com/live.m3u8")!
let initialSessionUrl = "https://your-mediatailor-session-url"

let builder = FLMediatailorFactory.createPlayerBuilder(
    contentUrl: contentUrl,
    initialSessionUrl: initialSessionUrl,
    contentType: .live
)

builder.build { adPlayer in
    // Use your configured Live AdPlayer instance
    adPlayer.adDelegate = self
}

Advanced Configuration Example

import FLAdvertisingMediatailor

// Configure session
let sessionConfig = MediaTailorSessionConfiguration.Builder()
    .reportingMode(.server)
    .overlayAvails(.on)
    .availSuppression(mode: .behindLiveEdge, "00:00:21")
    .adsParams(["targeting": "sports", "category": "premium"])
    .playerParams(["domain": "example.com", "version": "1.0"])
    .build()

// Configure ad policy
let adPolicy = AdPlaybackPolicy(
    fastForwardRule: .TRICK_FW_PLAY_LAST,
    rewindRule: .TRICK_RW_SKIP_ALL,
    interruptRule: .INTERRUPT_RESUME,
    autoSeekRule: .AUTO_SEEK_SKIP_ALL,
    repeatRule: .REPEAT_PLAY_ONCE
)

// Configure PAL
let palConfig = FLPALFactory.palConfiguration(
    willAdAutoPlay: .on,
    descriptionUrl: contentUrl,
    nonceLengthLimit: 3000,
    playerVersion: FLPlayer.version(),
    ppid: "unique-publisher-id",
    omidPartnerName: "YourAppName",
    omidPartnerVersion: Bundle.main.infoDictionary?["CFBundleVersion"] as? String ?? "1.0",
    omidVersion: [OMIDSDK versionString]
)

// Build player with all configurations
let builder = FLMediatailorFactory.createPlayerBuilder(
    contentUrl: contentUrl,
    initialSessionUrl: initialSessionUrl,
    contentType: .vod
)
.withSessionConfiguration(sessionConfig)
.withAdPlaybackPolicy(adPolicy)
.withPALConfig(palConfig)
.withLoadMediaTimeout(10.0)

builder.build { adPlayer in
    // Fully configured MediaTailor player ready for use
    adPlayer.adDelegate = self
}

API Reference

FLMediatailorFactory

The primary factory class for creating MediaTailor player builders.

public static func createPlayerBuilder(
    contentUrl: URL,
    initialSessionUrl: String,
    contentType: ContentType
) -> MediaTailorPlayerBuilder

Parameter	Type	Required	Description
contentUrl	URL	Yes	The playback URL for the content.
initialSessionUrl	String	Yes	The initial session URL for MediaTailor.
contentType	ContentType	Yes	Content type: `.vod` or `.live`.

MediaTailorPlayerBuilder

A fluent builder pattern for configuring MediaTailor players with optional parameters.

Configuration Methods

Method	Parameter Type	Description
`withSessionConfiguration`	MediaTailorSessionConfiguration	Custom session configuration for ad behavior.
`withAdPlaybackPolicy`	AdPlaybackPolicy	Policy handler to customize ad playback behavior.
`withPALConfig`	PALSessionConfiguration	PAL session configuration for Google PAL integration.
`withLoadMediaTimeout`	TimeInterval	Timeout for media loading and ad tracking requests.

Build Methods

Creates the configured MediaTailor player instance.

public func build(completion: @escaping (MediaTailorAdPlayer) -> Void)
public func build(httpClient: HTTPClient, completion: @escaping (MediaTailorAdPlayer) -> Void)

Configuration Options

MediaTailorSessionConfiguration

Configures session-level behavior for MediaTailor ad insertion.

Builder Pattern

let sessionConfig = MediaTailorSessionConfiguration.Builder()
    .reportingMode(.server)
    .overlayAvails(.on)
    .availSuppression(mode: .behindLiveEdge, "00:00:21")
    .adsParams(["targeting": "sports", "category": "premium"])
    .playerParams(["domain": "example.com", "version": "1.0"])
    .build()

Configuration Parameters

Parameter	Type	Default	Description
reportingMode	ReportingMode	`.client`	Ad tracking reporting mode.
overlayAvails	OverlayAvails	`.off`	Enable/disable overlay ad availability.
availSuppression	AvailSuppression	nil	Suppress ads for live content behind live edge.
adsParams	[String: String]	[:]	Additional parameters for ad requests.
playerParams	[String: String]	[:]	Player-specific parameters for MediaTailor.

AdPlaybackPolicy

Defines rules for ad playback behavior during various user interactions. to know more

let adPolicy = AdPlaybackPolicy(
    fastForwardRule: .TRICK_FW_PLAY_LAST,
    rewindRule: .TRICK_RW_SKIP_ALL,
    interruptRule: .INTERRUPT_RESUME,
    autoSeekRule: .AUTO_SEEK_SKIP_ALL,
    repeatRule: .REPEAT_PLAY_ONCE
)

PAL Configuration

Configure Google Publisher Advertiser Library (PAL) for enhanced ad targeting and measurement. to know more

let palConfig = FLPALFactory.palConfiguration(
    willAdAutoPlay: .on,
    descriptionUrl: contentUrl,
    nonceLengthLimit: 3000,
    playerVersion: FLPlayer.version(),
    ppid: "unique-publisher-id",
    omidPartnerName: "YourAppName",
    omidPartnerVersion: Bundle.main.infoDictionary?["CFBundleVersion"] as? String ?? "1.0",
    omidVersion: [OMIDSDK versionString]
)

MediaTailorAdPlayer

The player instance that combines AdPlayer functionality with PAL session integration.

public protocol MediaTailorAdPlayer: AdPlayer, PALSessionClient {}

Properties

Property	Type	Description
adDelegate	AdDelegate	Delegate to receive ad playback events.

Listening to Ad Delegate Methods

The client can set adDelegate 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

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
vastProperties	VASTProperties	Represents key VAST properties to be shared with all registered verification providers.

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

tvOS Limitations

When using tvOS system controller for MediaTailor playback:

Live Playback: InterstitialEvent won't be available
VOD Playback: Interstitial event once updated is not modified (cue points that are played are not removed)

Overview​

Key Features​

Getting Started​

Basic VOD Playback​

Basic Live Playback​

Advanced Configuration Example​

API Reference​

FLMediatailorFactory​

MediaTailorPlayerBuilder​

Configuration Methods​

Build Methods​

Configuration Options​

MediaTailorSessionConfiguration​

Builder Pattern​

Configuration Parameters​

AdPlaybackPolicy​

PAL Configuration​

MediaTailorAdPlayer​

Properties​

Listening to Ad Delegate Methods​

Ad Metadata​

AdBreak​

Ad​

VASTProperties​

tvOS Limitations​