Server Side Ad Insertion using Google IMA

GoogleIMA

Supported GoogleIMA SDK version

• iOS 3.22.1
• tvOS 4.12.0

Specifications

1. Server-side ads insertion (SSAI) a.k.a Dynamic Ad Insertion (DAI) provides a combined video stream of ads and content (ads stitching), resulting in a seamless, broadcast-like viewing experience. QP Google IMA ads player supports:
2. Various ad formats, including standard linear and non-linear in-stream ads, interactive in-stream ads, and skippable ads.
3. Multiple ad placements: It can deliver pre-roll, mid-roll, and post-roll ads.
4. Can make ad requests to Google Ad Manager, the Google AdSense network, or any VAST-compliant ad server.
5. Replacement for all ad tag parameters used for the upcoming ad requests in a Live IMA DAI Streams.

Usage

Integration Document for Google IMA DAI Create AdRequest for VOD

The adRequest method creates a Google IMA SSAI Ad request for VOD. It requires the content source ID and video ID to determine the specific video stream and its source. Additionally, you can configure optional parameters such as ad overlay UI scopes, media load timeout, and language tags.

Method Signature

public static func adRequest(contentSourceID: String, videoID: String, adOverlayUIScope: [AdOverlayUIScope]? = nil, loadMediaTimeout: TimeInterval? = nil, languageTag: String? = nil) -> GoogleIMAAdRequest

Property	Type	Description
contentSourceID	String	The content source ID for the stream request.
videoID	String	The video ID for the stream request.
adOverlayUIScope	[AdOverlayUIScope]?	An array of AdOverlayUIScope that contains the friendly obstruction views (optional).
loadMediaTimeout	TimeInterval?	Timeout for loading a video ad media file. If loading takes longer than this timeout, the ad playback is canceled and the next ad in the pod plays (optional, default is 8 seconds).
languageTag	String	The specified IETF BCP 47 language subtag string for the language used to display text for ads related labels (optional).

Example Usage

Example usage of VOD request with optional parameters:

// Create a UIView that will overlay the player
let overlayView = UIView()
// Define the purpose and reason for the overlay
let overlayPurpose = AdOverlayPurpose.somePurpose
let overlayReason = "To display additional information"
// Instantiate AdOverlayUIScope
let adOverlayUIScope = AdOverlayUIScope(view: overlayView, purpose: overlayPurpose, reason: overlayReason)
// Create an ad request with required and optional parameters
let adRequest = FLAdvertisingGoogleIMAFactory.adRequest( contentSourceID: "2528370",
                                                         videoID: "tears-of-steel",
                                                         adOverlayUIScope: [adOverlayUIScope],
                                                         loadMediaTimeout: 10,
                                                         languageTag: "en"
)

Create AdRequest for GoogleIMAPlayer

The adRequest method creates a Google IMA SSAI Ad request for live streams. It requires the asset key to identify the specific live stream. Additionally, you can configure optional parameters such as ad overlay UI scopes, media load timeout, language tags, and ad tag parameters. Method Signature

public static func adRequest(assetKey: String, adOverlayUIScope: [AdOverlayUIScope]? = nil, loadMediaTimeout: TimeInterval? = nil, languageTag: String? = nil, adTagParameters: [String: String]? = nil) -> GoogleIMAAdRequest

Integration Document for Google IMA DAI Create AdRequest for LIVE

Property	Type	Description
assetKey	String	Identifier of the live stream. This is used to
determine which stream should be played.
adOverlayUIScope	[AdOverlayUIScope]?	An array of AdOverlayUIScope that contains the friendly obstruction views (optional).
loadMediaTimeout	TimeInterval?	Timeout for loading a video ad media file. If loading takes longer than this timeout, the ad playback is canceled and the next ad in the pod plays (optional, default is 8 seconds).
languageTag	String?	The specified IETF BCP 47 language subtag string for the language used to display text for ads related labels (optional).
adTagParameters	[String: String]?	Replaces all of the ad tag parameters used for upcoming ad requests for a live stream (optional)..

Example Usage

Example usage of Live request with optional parameters:

// Create a UIView that will overlay the player
let overlayView = UIView()
// Define the purpose and reason for the overlay
let overlayPurpose = AdOverlayPurpose.somePurpose
let overlayReason = "To display additional information"
// Instantiate AdOverlayUIScope
let adOverlayUIScope = AdOverlayUIScope(view: overlayView, purpose: overlayPurpose, reason: overlayReason)
let adRequest = FLAdvertisingGoogleIMAFactory.adRequest( assetKey: "PSzZMzAkSXCmlJOWDmRj8Q", adOverlayUIScope: [adOverlayUIScope], 
                   loadMediaTimeout: 10,
                   languageTag: "en",
                   adTagParameters: ["param1": "value1", "param2": "value2"]
)

Create Content Player with URLAsset

let player = FLPlatformPlayerFactory.player(asset: urlAsset, thumbnailConfiguration: thumbnailConfiguration)

Create the Ad Player

Create an ad player using the main content Player, GoogleIMAAdRequest, and UIViewController. Note that the created ad player cannot be used standalone as it only manages Google IMA Ad playback. The main content playback is not managed by this ad player. The UIViewController should be the parent of the playback view. Method Signature.

public static func adPlayer(contentPlayer: Player, request: GoogleIMAAdRequest, shouldSupportPIP: Bool = false, playerViewControllerCallback: @escaping () -> UIViewController) -> GoogleIMAAdPlayer

Property	Type	Description
contentPlayer	Player	The main content player.
request	GoogleIMAAdRequest	The Google IMA ad request of type GoogleIMAAdRequest such as GoogleCSAIRequest GoogleDAIVODRequest, GoogleDAILIVERequest.
shouldSupportPIP	Bool	Specifies whether the player should support Picture-in-Picture (PIP) mode. The default value is false.
playerViewControllerCallback	@escaping () ->
UIViewController	The main content player.	A closure that lazily returns the UIViewController used for playback. Required to return the UIViewController where the playback view is attached.

Example Usage

Example usage of AdPlayer creation with optional parameters:

// Create the ad player
let adPlayer = FLAdvertisingGoogleIMAFactory.adPlayer( contentPlayer: player,
request: adRequest,
shouldSupportPIP: true
){
return viewController
}

Create the AdComposablePlayer

Create an ad composed player that manages both the main content player and the ad player, providing a seamless main content playback with GoogleIMA ads served as per the GoogleIMA Ad response.

Method Signature

public static func adComposablePlayer(contentPlayer: Player, adPlayer: GoogleIMAAdPlayer) -> AdComposablePlayer

Parameter	Type	Description
contentPlayer	Player	The main content player.
adPlayer	GoogleIMAAdPlayer	The main content player.

Example Usage

Example usage of AdComposablePlayer creation:

// Create the ad composed player
let adComposedPlayer = FLAdvertisingGoogleIMAFactory.adComposablePlayer( contentPlayer: player,
adPlayer: adPlayer
)