To enable the Video Stitcher API for your project, please reach out to your Account Representative or contact Sales to learn more.

Use the IMA DAI SDK on iOS

Play VOD streams registered with Google Cloud Video Stitcher API

This guide demonstrates how to use the IMA DAI SDK for iOS to request and play a Google Cloud VOD stream session .

This guide expands on the basic example from the Get started guide for IMA DAI.

For information on integrating with other platforms or on using the IMA client-side SDKs, see Interactive Media Ads SDKs .

If you would like to view or follow along with a completed sample integration, download the Cloud video stitcher example for Objective-C or Swift .

Set up a Google Cloud project

Enter the following variables for use in the IMA SDK:

Location

The Google Cloud region where your VOD config was created:

 LOCATION

Project number

The Google Cloud project number using the Video Stitcher API:

 PROJECT_NUMBER

OAuth token

A service account's short lived OAuth token with the Video Stitcher user role:

 OAUTH_TOKEN

Read more about creating short-lived OAuth tokens . The OAuth token can be reused across multiple requests as long as it has not expired.

Network code

The Ad Manager network code for requesting ads: NETWORK_CODE

VOD config ID

The VOD config ID for the VOD stream: VOD_CONFIG_ID

Read more about creating the VOD config ID in the Cloud stitching create a VOD config guide .

User context: The user context for tracking requests. Can be nil . Defaults to nil in this guide.

Set up the basic example

Go to the IMA iOS DAI GitHub release page and download the basic Objective-C example. This example is an iOS Xcode project that relies on Cocoapods to load the IMA DAI SDK. If you're using Swift, IMA doesn't have an iOS sample app, but check out the Swift code snippet later in this guide for how to implement an IMAVideoStitcherVODStreamRequest in your own app.

To prepare the sample to run, make sure CocoaPods is installed , then open the basic example's folder in the terminal and run the following command:

 pod  
install  
--repo-update

Once that command completes, you see a file named BasicExample.xcworkspacein your project folder. Open this file in Xcode and run the sample to ensure that the test video and ads play as expected.

Request a VOD stream

To replace the sample stream with your ad stitched VOD stream, use IMAVideoStitcherVODStreamRequest to create an ad session with Google Ad Manager. You can use the Google Ad Manager UI to locate the generated DAI sessions for monitoring and debugging.

In the existing sample, there are examples for requesting a VOD stream or a livestream from Google's DAI servers. To make it work with the Google Cloud Video Stitcher API, you need to replace the current requestStream function with one that uses the IMAVideoStitcherVODStreamRequest class.

Here's an example:

Objective-C

ViewController.m

  ... 
 #import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h> 
  /// The Stream's VOD config ID. 
 static 
  
 NSString 
  
 * 
 const 
  
 kVODConfigID 
  
 = 
  
 @" VOD_CONFIG_ID 
" 
 ; 
 /// The Network Code used by the Video Stitcher API. 
 static 
  
 NSString 
  
 * 
 const 
  
 kNetworkCode 
  
 = 
  
 @" NETWORK_CODE 
" 
 ; 
 /// The Google Cloud project using the Video Stitcher API. 
 static 
  
 NSString 
  
 * 
 const 
  
 kProjectNumber 
  
 = 
  
 @" PROJECT_NUMBER 
" 
 ; 
 /// The Google Cloud region containing your project. 
 static 
  
 NSString 
  
 * 
 const 
  
 kLocation 
  
 = 
  
 @" LOCATION 
" 
 ; 
 /// An OAuth Token created by a Google Cloud account with Video Stitcher API 
 /// permissions. 
 static 
  
 NSString 
  
 * 
 const 
  
 kOAuthToken 
  
 = 
  
 @" OAUTH_TOKEN 
" 
 ; 
 /// Fallback URL in case something goes wrong in loading the stream. If all goes well, this will not 
 /// be used. 
 static 
  
 NSString 
  
 * 
 const 
  
 kBackupStreamURLString 
  
 = 
  
 @"http://googleimadev-vh.akamaihd.net/i/big_buck_bunny/bbb-,480p,720p,1080p,.mov.csmil/" 
  
 @"master.m3u8" 
 ; 
 @interface 
 ViewController 
  
 () 
  
< IMAAdsLoaderDelegate 
 , 
  
 IMAStreamManagerDelegate 
> ... 
 - 
  
 ( 
 void 
 ) 
 requestStream 
  
 { 
  
 // Create an ad display container for ad rendering. 
  
 IMAAdDisplayContainer 
  
 * 
 adDisplayContainer 
  
 = 
  
 [[ 
 IMAAdDisplayContainer 
  
 alloc 
 ] 
  
 initWithAdContainer 
 : 
 self 
 . 
 videoView 
  
 viewController 
 : 
 self 
  
 companionSlots 
 : 
 nil 
 ]; 
  
 // Create an IMAAVPlayerVideoDisplay to give the SDK access to your video player. 
  
 IMAAVPlayerVideoDisplay 
  
 * 
 imaVideoDisplay 
  
 = 
  
 [[ 
 IMAAVPlayerVideoDisplay 
  
 alloc 
 ] 
  
 initWithAVPlayer 
 : 
 self 
 . 
 contentPlayer 
 ]; 
  
  IMAVideoStitcherVODStreamRequest 
  
 * 
 streamRequest 
  
 = 
  
 [[ 
 IMAVideoStitcherVODStreamRequest 
  
 alloc 
 ] 
  
 initWithVODConfigID 
 : 
 kVODConfigID 
  
 region 
 : 
 kLocation 
  
 projectNumber 
 : 
 kProjectNumber 
  
 OAuthToken 
 : 
 kOAuthToken 
  
 networkCode 
 : 
 kNetworkCode 
  
 adDisplayContainer 
 : 
 adDisplayContainer 
  
 videoDisplay 
 : 
 imaVideoDisplay 
  
 userContext 
 : 
 nil 
  
 videoStitcherSessionOptions 
 : 
 nil 
 ]; 
  
 [ 
 self 
 . 
 adsLoader 
  
 requestStreamWithRequest 
 : 
 streamRequest 
 ]; 
 } 
 ...

Swift

ViewController.swift

  ... 
 class 
  
 ViewController 
 : 
  
 UIViewController 
 , 
  
 IMAAdsLoaderDelegate 
 , 
  
 IMAStreamManagerDelegate 
  
 { 
  
  /// The Stream's VOD config ID. 
  
 static 
  
 let 
  
 vodConfigID 
  
 = 
  
 " VOD_CONFIG_ID 
" 
  
 /// The Network Code used by the Video Stitcher API. 
  
 static 
  
 let 
  
 networkCode 
  
 = 
  
 " NETWORK_CODE 
" 
  
 /// The Google Cloud project using the Video Stitcher API. 
  
 static 
  
 let 
  
 projectNumber 
  
 = 
  
 " PROJECT_NUMBER 
" 
  
 /// The Google Cloud region containing your project. 
  
 static 
  
 let 
  
 location 
  
 = 
  
 " LOCATION 
" 
  
 /// An OAuth Token created by a Google Cloud account with Video Stitcher API 
  
 /// permissions. 
  
 static 
  
 let 
  
 oAuthToken 
  
 = 
  
 " OAUTH_TOKEN 
" 
  
 /// Fallback URL in case something goes wrong in loading the stream. If all goes well, this will 
  
 /// not be used. 
  
 static 
  
 let 
  
 backupStreamURLString 
  
 = 
  
 """ 
 http://googleimadev-vh.akamaihd.net/i/big_buck_bunny/\ 
 bbb-,480p,720p,1080p,.mov.csmil/master.m3u8 
 """ 
  
 ... 
  
 func 
  
 requestStream 
 () 
  
 { 
  
 // Create an ad display container for ad rendering. 
  
 adDisplayContainer 
  
 = 
  
 IMAAdDisplayContainer 
 ( 
  
 adContainer 
 : 
  
 videoView 
 , 
  
 viewController 
 : 
  
 self 
 , 
  
 companionSlots 
 : 
  
 nil 
 ) 
  
 // Create an IMAAVPlayerVideoDisplay to give the SDK access to your video player. 
  
 let 
  
 imaVideoDisplay 
  
 = 
  
 IMAAVPlayerVideoDisplay 
 ( 
 avPlayer 
 : 
  
 contentPlayer 
 !) 
  
  // Create a VOD stream request. 
  
 let 
  
 streamRequest 
  
 = 
  
 IMAVideoStitcherVODStreamRequest 
 ( 
  
 VODConfigID 
 : 
  
 ViewController 
 . 
 vodConfigID 
 , 
  
 region 
 : 
  
 ViewController 
 . 
 location 
 , 
  
 projectNumber 
 : 
  
 ViewController 
 . 
 projectNumber 
 , 
  
 oAuthToken 
 : 
  
 ViewController 
 . 
 oAuthToken 
 , 
  
 networkCode 
 : 
  
 ViewController 
 . 
 networkCode 
 , 
  
 adDisplayContainer 
 : 
  
 adDisplayContainer 
 !, 
  
 videoDisplay 
 : 
  
 imaVideoDisplay 
 , 
  
 userContext 
 : 
  
 nil 
 , 
  
 videoStitcherSessionOptions 
 : 
  
 nil 
 ) 
  
 adsLoader 
 ?. 
 requestStream 
 ( 
 with 
 : 
  
 streamRequest 
 ) 
  
 } 
  
 ...

Run the project, then you can request and play your custom VOD stream.

(Optional) Add streaming session options

Customize your stream request by adding session options to override the default Cloud Video Stitcher API configuration by populating the videoStitcherSessionOptions parameter in your IMAVideoStitcherVODStreamRequest . If you provide an unrecognized option, the Cloud Video Stitcher API will respond with an HTTP 400 error. Consult the troubleshooting guide for assistance.

For example, you can override the manifest options with the following code snippet, which requests two stream manifests with renditions ordered from lowest bitrate to highest.

Objective-C

   
  // Define session options JSON string. 
  
 // The following session options are examples. Use session options 
  
 // that are compatible with your video stream. 
  
 NSString 
  
 * 
 sessionOptionsStr 
  
 = 
  
 @"{" 
  
 " 
 \" 
 manifestOptions 
 \" 
 : {" 
  
 " 
 \" 
 bitrateOrder 
 \" 
 : 
 \" 
 ascending 
 \" 
 " 
  
 "  }" 
  
 "}" 
 ; 
  
 // convert JSON NSString to NSDictionary 
  
 NSData 
  
 * 
 sessionOptionsData 
  
 = 
  
 [ 
 sessionOptionsStr 
  
 dataUsingEncoding 
 : 
 NSUTF8StringEncoding 
 ]; 
  
 NSError 
  
 * 
 error 
  
 = 
  
 nil 
 ; 
  
 NSDictionary 
  
 * 
 sessionOptions 
  
 = 
  
 [ 
 NSJSONSerialization 
  
 JSONObjectWithData 
 : 
 sessionOptionsData 
  
 options 
 : 
 0 
  
 error 
 : 
& error 
 ]; 
  
 // make stream request 
  
 IMAVideoStitcherVODStreamRequest 
  
 * 
 streamRequest 
  
 = 
  
 [[ 
 IMAVideoStitcherVODStreamRequest 
  
 alloc 
 ] 
  
 initWithVODConfigID 
 : 
 kVODConfigID 
  
 region 
 : 
 kLocation 
  
 projectNumber 
 : 
 kProjectNumber 
  
 OAuthToken 
 : 
 kOAuthToken 
  
 networkCode 
 : 
 kNetworkCode 
  
 adDisplayContainer 
 : 
 adDisplayContainer 
  
 videoDisplay 
 : 
 imaVideoDisplay 
  
 userContext 
 : 
 nil 
  
  videoStitcherSessionOptions 
 : 
 sessionOptions 
 ]; 
  
 [ 
 self 
 . 
 adsLoader 
  
 requestStreamWithRequest 
 : 
 streamRequest 
 ];

Swift

   
  // Define session options JSON string. 
  
 // The following session options are examples. Use session options 
  
 // that are compatible with your video stream. 
  
 let 
  
 sessionOptionsStr 
  
 = 
  
 """ 
 { 
  
 " 
 manifestOptions 
 " 
 : { 
  
 " 
 bitrateOrder 
 " 
 : 
 " 
 ascending 
 " 
 } 
 } 
 """ 
  
 // convert JSON string to dictionary 
  
 guard 
  
 let 
  
 sessionOptionsData 
  
 = 
  
 sessionOptionsStr 
 . 
 data 
 ( 
 using 
 : 
  
 . 
 utf8 
 , 
  
 allowLossyConversion 
 : 
  
 false 
 ) 
  
 else 
  
 { 
  
 return 
  
 nil 
  
 } 
  
 let 
  
 sessionOptions 
  
 = 
  
 try 
 ? 
  
 JSONSerialization 
 . 
 jsonObject 
 ( 
 with 
 : 
  
 sessionOptionsData 
 , 
  
 options 
 : 
  
 . 
 mutableContainers 
 ) 
  
 // make stream request 
  
 let 
  
 streamRequest 
  
 = 
  
 IMAVideoStitcherVODStreamRequest 
 ( 
  
 vodConfigID 
 : 
 ViewController 
 . 
 vodConfigID 
  
 region 
 : 
 ViewController 
 . 
 location 
  
 projectNumber 
 : 
 ViewController 
 . 
 projectNumber 
  
 OAuthToken 
 : 
 ViewController 
 . 
 oAuthToken 
  
 networkCode 
 : 
 ViewController 
 . 
 networkCode 
  
 adDisplayContainer 
 : 
 adDisplayContainer 
  
 videoDisplay 
 : 
 imaVideoDisplay 
  
 userContext 
 : 
 nil 
  
  videoStitcherSessionOptions 
 : 
 sessionOptions 
 ) 
  
 adsLoader 
 ?. 
 requestStream 
 ( 
 with 
 : 
  
 streamRequest 
 )

Clean up

Now that you have successfully hosted a VOD stream using the Google Cloud Video Stitcher API and requested it using the IMA DAI SDK for iOS, it's important to clean up any serving resources.

Follow the VOD clean up guide to remove any unneeded resources and assets.

HTML5

Roku

Use the IMA DAI SDK on iOS Stay organized with collections Save and categorize content based on your preferences.

Play VOD streams registered with Google Cloud Video Stitcher API

Set up a Google Cloud project

Set up the basic example

Request a VOD stream

Objective-C

Swift

(Optional) Add streaming session options

Objective-C

Swift

Clean up

Use the IMA DAI SDK on iOS