Get started with the IMA DAI SDK

IMA SDKs make it easy to integrate multimedia ads into your websites and apps. IMA SDKs can request ads from any VAST-compliant ad server and manage ad playback in your apps. With IMA DAI SDKs, apps make a stream request for ad and content video—either VOD or live content. The SDK then returns a combined video stream, so that you don't have to manage switching between ad and content video within your app.

Select the DAI solution you're interested in

Pod Serving DAI

This guide demonstrates how to play a DAI Pod Serving live or VOD stream using the IMA DAI SDK for tvOS with a video player. To view or follow a completed sample integration, download the Pod Serving example app (Obj C or Swift).

IMA DAI Pod Serving overview

Implementing Pod Serving using the IMA DAI SDK for tvOS involves two main components:

• StreamRequest: An object that defines a stream request to Google's advertising servers. Must be created using either IMAPodStreamRequest or IMAPodVODStreamRequest to enable Pod Serving. Both methods require a Network Code and IMAPodStreamRequest also needs a Custom Asset Key. An API Key is optional.

• IMAStreamManager: An object that handles communication between the video stream and the IMA DAI SDK, such as firing tracking pings and forwarding stream events to the publisher.

Prerequisites

Before you begin, you need the following:

• Xcode 13 or later.
• CocoaPods (preferred), Swift Package Manager, or a downloaded copy of the IMA DAI SDK for tvOS.
• A tvOS app already set up with the IMA DAI SDK to play video streams with DAI ads. If you don't already have such an app, we recommend using the tvOS DAI BasicExample as a starting point. The BasicExample has the codebase referenced in this guide. For more information about how to implement the IMA DAI SDK, see the Quick start guide.

Set up your Pod Serving variables

All changes needed for Pod Serving are done in ViewController.swift in Swift or ViewController.m in Objective-C. The snippets in this guide default to using the Swift language. The first step is to update the constant variables.

Here are the ad pod stream request constants to be added:

• STREAM_URL (Only used for livestreams): The video stream URL provided by your manifest manipulator or third-party partner using Pod Serving. It should require you to insert the stream ID provided by the IMA DAI SDK, before you make a request. In this case, the stream URL includes a placeholder, "[[STREAMID]]", which is replaced with the stream ID, before making a request.
• NETWORK_CODE: The network code for your Ad Manager 360 account.
• CUSTOM_ASSET_KEY (Only used for livestreams): The custom asset key that identifies your Pod Serving event in Ad Manager 360. This can be created by your manifest manipulator or 3rd party Pod Serving partner.
• API_KEY (Only used for livestreams): An optional API key that can be required to retrieve a stream ID from the IMA DAI SDK.

Change the example's variable section to match the following:

...
class ViewController:
  UIViewController,
  IMAAdsLoaderDelegate,
  IMAStreamManagerDelegate,
  AVPlayerViewControllerDelegate
{
  static let streamUrl =
    "https://encodersim.sandbox.google.com/masterPlaylist/9c654d63-5373-4673-8c8d-6d92b66b9d46/master.m3u8?gen-seg-redirect=true&network=51636543&event=google-sample&pids=devrel4628000,devrel896000,devrel3528000,devrel1428000,devrel2628000,devrel1928000&seg-host=dai.google.com&stream_id=[[STREAMID]]"
  static let networkCode = "51636543"
  static let customAssetKey = "google-sample"
  static let APIKey = ""
  static let backupStreamURLString =
    "http://googleimadev-vh.akamaihd.net/i/big_buck_bunny/bbb-,480p,720p,1080p,.mov.csmil/master.m3u8"

  var adsLoader: IMAAdsLoader?
  ...

Create either a live or VOD pod stream request

  ...

  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)

    // Create a podserving stream request.
    request = IMAPodStreamRequest(
      networkCode: self.networkCode,
      customAssetKey: self.customAssetKey,
      adDisplayContainer: adDisplayContainer,
      videoDisplay: self.videoDisplay,
      userContext: nil)

    adsLoader.requestStream(with: request)
  }

  ...

  ...

  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)

    // Create a podserving stream request.
    request = IMAPodVODStreamRequest(
      networkCode: self.networkCode,
      adDisplayContainer: adDisplayContainer,
      videoDisplay: self.videoDisplay,
      userContext: nil)

    adsLoader.requestStream(with: request)
  }

  ...

Edit and set the stream URL

  ...

  // MARK: - IMAAdsLoaderDelegate
  func adsLoader(_ loader: IMAAdsLoader!, adsLoadedWith adsLoadedData: IMAAdsLoadedData!) {
    let streamManager = adsLoadedData.streamManager
    let streamId = streamManager.streamId
    let urlString = streamUrl.replacingOccurrences(of: "[[STREAMID]]", with: streamId)
    let loadedStreamUrl = URL(string:urlString)
    self.videoDisplay.loadStream(loadedStreamUrl, subtitles:@[])
    self.videoDisplay.play()
    streamManager.delegate = self
    streamManager.initialize(with: nil)
    self.streamManager = streamManager
  }

  ...

  ...

  // MARK: - IMAAdsLoaderDelegate
  func adsLoader(_ loader: IMAAdsLoader!, adsLoadedWith adsLoadedData: IMAAdsLoadedData!) {
    let streamManager = adsLoadedData.streamManager
    let streamId = streamManager.streamId
    // 'vtpInterface' is a place holder for your own video technology partner
    // (VTP) API calls.
    let streamUrl = vtpInterface.requestStreamURL(streamID)
    self.streamManager.loadThirdPartyStream(streamUrl, streamSubtitles:@[])
    streamManager.delegate = self
    streamManager.initialize(with: nil)
    self.streamManager = streamManager
  }

Clean up IMA DAI assets

When you have successfully finished requesting and displaying ads in a Pod Serving stream with IMA DAI SDK, we suggest you clean up any resources after the Pod Serving session is complete. Call IMAStreamManager.destroy() to stop stream playback, stop all ad tracking, and release all of the loaded stream assets.

To see other examples of the tvOS SDK being used, see samples on GitHub.