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 stream, using the IMA DAI SDK with a video player for live and VOD stream playback. To view or follow a completed sample integration, download the Pod Serving example.

IMA DAI Pod Serving overview

StreamRequest: An object that defines a stream request to Google's advertising servers. Must be created using either ImaSdkFactory.createPodStreamRequest() or ImaSdkFactory.createPodVodStreamRequest() to enable Pod Serving. These methods require a Network Code, and createPodStreamRequest also requires a Custom Asset Key, and an optional API key. Both include other optional parameters.
StreamManager: 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

An Android 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 Android DAI BasicExample as a starting point. The BasicExample has the codebase referenced in this guide.
It's important for your app to send ID3 events using VideoStreamPlayerCallback.onUserTextReceived() for IMA DAI to function. See this Full service DAI code snippet example.

Set up your Pod Serving variables

All changes needed for Pod Serving are done in SampleAdsWrapper.java. 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 third-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.

The Android DAI BasicExample is designed to play a variety of different stream types, but for Pod Serving, it is set up to just play a single stream. Change the example's variable section to match the following:

/** This class adds ad-serving support to Sample HlsVideoPlayer */
public class SampleAdsWrapper
        implements AdEvent.AdEventListener, AdErrorEvent.AdErrorListener, AdsLoader.AdsLoadedListener {

  // Podserving Stream Constants.
  private static final String STREAM_URL =
          "https://encodersim.sandbox.google.com/masterPlaylist/9c654d63-5373-4673-8c8d-6d92b66b9d46/" +
          "master.m3u8?gen-seg-redirect=true&amp;network=51636543&amp;event=google-sample" +
          "&amp;pids=devrel4628000,devrel896000,devrel3528000,devrel1428000,devrel2628000,devrel1928000" +
          "&amp;seg-host=dai.google.com&amp;stream_id=[[STREAMID]]";
  private static final String NETWORK_CODE = "51636543";
  private static final String CUSTOM_ASSET_KEY = "google-sample";
  private static final String API_KEY = "";

  private static final String PLAYER_TYPE = "DAISamplePlayer";

  /** Log interface, so we can output the log commands to the UI or similar. */
  public interface Logger {

...

Create a live or VOD pod stream request to enable Pod Serving

Live stream Pod Serving

Remove the method buildStreamRequest() which had been used to switch between building a variety of stream types. Then, change requestAndPlayAds() to call ImaSdkFactory.createPodStreamRequest() to create a Live Pod Serving ad request. Finally, request the stream using AdsLoader.requestStream().

public void requestAndPlayAds() {
  StreamRequest request =
      sdkFactory.createPodStreamRequest(NETWORK_CODE, CUSTOM_ASSET_KEY, API_KEY);
  request.setFormat(StreamFormat.HLS);

  adsLoader.addAdErrorListener(this);
  adsLoader.addAdsLoadedListener(this);
  adsLoader.requestStream(request);
}

VOD stream Pod Serving

Remove the method buildStreamRequest() which had been used to switch between building a variety of stream types. Then, change requestAndPlayAds() to call ImaSdkFactory.createPodVodStreamRequest() to create a VOD Pod Serving ad request. Finally, request the stream using AdsLoader.requestStream().

public void requestAndPlayAds() {
  StreamRequest request =
      sdkFactory.createPodVodStreamRequest(NETWORK_CODE);
  request.setFormat(StreamFormat.HLS);

  adsLoader.addAdErrorListener(this);
  adsLoader.addAdsLoadedListener(this);
  adsLoader.requestStream(request);
}

Edit and set the stream URL

Live stream Pod Serving

Call StreamManager.getStreamId() to get the stream ID. This then needs to be inserted into the STEAM_URL replacing "[[STREAMID]]". After this change is made, the new stream URL can be set using videoPlayer.setStreamUrl().

@Override
public void onAdsManagerLoaded(AdsManagerLoadedEvent event) {
  streamManager = event.getStreamManager();
  streamManager.addAdErrorListener(this);
  streamManager.addAdEventListener(this);

  // To enable streams
  String streamID = streamManager.getStreamId();
  String streamUrl = STREAM_URL.replace("[[STREAMID]]", streamID);

  streamManager.init();

  videoPlayer.setStreamUrl(streamUrl);
  videoPlayer.play();
}

VOD stream Pod Serving

Call StreamManager.getStreamId() to get the stream ID. Then, request a stream URL from your video technology partner (VTP). Then call StreamManager.loadThirdPartyStream() to have IMA load the stream URL and any subtitles returned by your TVP.

@Override
public void onAdsManagerLoaded(AdsManagerLoadedEvent event) {
  streamManager = event.getStreamManager();
  streamManager.addAdErrorListener(this);
  streamManager.addAdEventListener(this);

  // To enable streams
  String streamID = streamManager.getStreamId();
  // 'vtpInterface' is a place holder for your own video technology partner
  // (VTP) API calls.
  String streamUrl = vtpInterface.requestStreamURL(streamID);

  streamManager.init();

  // Pass any subtitles returned by your VTP in this step as well.
  streamManager.loadThirdPartyStream(streamUrl, subtitles);
}

When Pod Serving is enabled, IMA doesn't make calls to VideoStreamPlayer.loadUrl(), so you can remove any calls to videoPlayer.setStreamUrl() and videoPlayer.play() from it.

That's it! You're now requesting and displaying ads in a Pod Serving stream with the IMA DAI SDK. To see other examples of the Android SDK being used, look to the samples on GitHub.