## Play VOD streams registered with Google Cloud Video Stitcher API


This guide demonstrates how to use the IMA DAI SDK for
tvOS to request and play a

[Google Cloud VOD stream
session](https://cloud.google.com/video-stitcher/docs/how-to/gam/vod/overview).


This guide expands on the basic example from the [Get started
guide](https://developers.google.com/interactive-media-ads/docs/sdks/tvos/dai)
for IMA DAI.

For information on integrating with other platforms or on using the IMA
client-side SDKs, see [Interactive Media Ads SDKs](https://developers.google.com/interactive-media-ads).

If you would like to view or follow along with a completed sample integration,
download the Cloud video stitcher example for
[Objective-C](https://github.com/googleads/googleads-ima-tvos-dai/tree/main/Objective-C/VideoStitcherExample)
or
[Swift](https://github.com/googleads/googleads-ima-tvos-dai/tree/main/Swift/VideoStitcherExample).
**Note:** Apple only provides frameworks to support [HTTP Live Streaming (HLS)](https://developer.apple.com/documentation/http_live_streaming), such as AVKit, AVFoundation, and WebKit. These frameworks won't work with DASH stream format.

## Set up a Google Cloud project


Enter the following variables for use in the IMA SDK:

Location
:   The [Google Cloud region](https://cloud.google.com/video-stitcher/docs/locations)
    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
    ```

    <br />

:   Read more about

    [creating short-lived OAuth
    tokens](https://cloud.google.com/video-stitcher/docs/how-to/gam/vod/prepare-client-app-gam#generate-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`

<br />

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](https://cloud.google.com/video-stitcher/docs/how-to/gam/vod/create-vod-configs#create-vod-config).


## Set up the basic example

Go to the
[IMA tvOS DAI GitHub release page](https://github.com/googleads/googleads-ima-tvos-dai/releases)
and download the basic example in Objective-C or Swift, depending on your
language of choice. This example is a tvOS Xcode project that relies on
Cocoapods to load the IMA DAI SDK.

> [!IMPORTANT]
> **Important:** IMA DAI SDK [v4.13.0](https://developers.google.com/ad-manager/dynamic-ad-insertion/sdk/tvos/history) or later is required. Update the pod file as needed.

To prepare the sample to run, make sure [CocoaPods is installed](https://guides.cocoapods.org/using/getting-started.html), then open the basic
example's folder in the terminal and run the following command:

```bash
pod install --repo-update
```

Once that command completes, you see a file named **BasicExample.xcworkspace**
in 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`](https://developers.google.com/ad-manager/dynamic-ad-insertion/sdk/tvos/reference/Classes/IMAVideoStitcherVODStreamRequest)
to create an ad session with Google Ad Manager. You can use the Google Ad
Manager UI to [locate the generated DAI sessions](https://support.google.com/admanager/answer/7257678) 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**

```objective-c
...

#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>

/// VideoStitcher VOD config ID.
static NSString \*const kVODConfigID = @"VOD_CONFIG_ID";
/// VideoStitcher Network Code.
static NSString \*const kNetworkCode = @"NETWORK_CODE";
/// VideoStitcher Project Number.
static NSString \*const kProjectNumber = @"PROJECT_NUMBER";
/// VideoStitcher Location.
static NSString \*const kLocation = @"LOCATION";
/// VideoStitcher OAuth Token.
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\] initWithAdTagURL:kVODConfigID
region:kLocation
projectNumber:kProjectNumber
OAuthToken:kOAuthToken
networkCode:kNetworkCode
adDisplayContainer:adDisplayContainer
videoDisplay:imaVideoDisplay
userContext:nil,
videoStitcherSessionOptions:nil\];
    [self.adsLoader requestStreamWithRequest:streamRequest];
}

...
```

### Swift

**ViewController.swift**

```swift
...

class ViewController:
  UIViewController,
  IMAAdsLoaderDelegate,
  IMAStreamManagerDelegate,
  AVPlayerViewControllerDelegate
{
  /// 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() {
    guard let playerViewController = self.playerViewController else { return }
    guard let adContainerView = self.adContainerView else { return }
    guard let adsLoader = self.adsLoader else { return }

    self.videoDisplay = IMAAVPlayerVideoDisplay(avPlayer: playerViewController.player!)
    adDisplayContainer = IMAAdDisplayContainer(
      adContainer: adContainerView, viewController: self)
    let streamRequest: IMAStreamRequest
    // Create a VOD stream request.
streamRequest = IMAVideoStitcherVODStreamRequest(
VODConfigID: ViewController.vodConfigID,
region: ViewController.location,
projectNumber: ViewController.projectNumber,
oAuthToken: ViewController.oAuthToken,
networkCode: ViewController.networkCode,
adDisplayContainer: adDisplayContainer!,
videoDisplay: self.videoDisplay,
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`](https://developers.google.com/ad-manager/dynamic-ad-insertion/sdk/tvos/reference/Classes/IMAVideoStitcherVODStreamRequest#videostitchersessionoptions)
parameter in your
[IMAVideoStitcherVODStreamRequest](https://developers.google.com/ad-manager/dynamic-ad-insertion/sdk/tvos/reference/Classes/IMAVideoStitcherVODStreamRequest).


If you provide an unrecognized option, the Cloud
Video Stitcher API will respond with an HTTP 400 error. Consult the
[troubleshooting guide](https://cloud.google.com/video-stitcher/docs/troubleshooting)
for assistance.

For example, you can override the
[manifest options](https://cloud.google.com/video-stitcher/docs/concepts/manifest-options)
with the following code snippet, which requests two stream manifests with
renditions ordered from lowest bitrate to highest.

### Objective-C

```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

```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)
```

<br />

## 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 tvOS, it's important to clean up any serving
resources.

Follow the

[VOD clean up](https://cloud.google.com/video-stitcher/docs/how-to/gam/vod/clean-up)
guide to remove any unneeded resources and assets.