Set up the IMA SDK for DAI

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

Full service Pod serving

Pod Serving DAI

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.

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.

Note: The IMA DAI SDK for Android supports both HLS and DASH streams.

This guide explains how to configure exoplayer and IMA DAI SDK to play an HLS stream. For an example of a video player supporting both HLS and DASH streams, see our Advanced Example.

Key Point: To use IMA DAI Pod Serving, you must be working with a Pod Serving partner and must have an Ad Manager 360 Advanced account. If you have an Ad Manager account, contact your account manager for more details. For information about signing up for Ad Manager, visit the Ad Manager Help Center.

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

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:

Note: The stream parameters provided are for a Live pod stream. To test with a Pod Serving VOD stream, you need to provide your own test stream parameters.

/** This class implements IMA to add pod ad-serving support to SampleVideoPlayer */
@SuppressLint("UnsafeOptInUsageError")
/* @SuppressLint is needed for new media3 APIs. */
public class SampleAdsWrapper
    implements AdEvent.AdEventListener, AdErrorEvent.AdErrorListener, AdsLoader.AdsLoadedListener {

  // Set up the pod serving variables.
  private static final String NETWORK_CODE = "";
  private static final String CUSTOM_ASSET_KEY = "";
  private static final String API_KEY = "";
  private static final String STREAM_URL = "";
  private static final StreamFormat STREAM_FORMAT = StreamFormat.HLS;
SampleAdsWrapper.java

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, modify requestAndPlayAds() to call ImaSdkFactory.createPodStreamRequest() to create a Live Pod Serving ad request.

// Live pod stream request.
request = sdkFactory.createPodStreamRequest(NETWORK_CODE, CUSTOM_ASSET_KEY, API_KEY);
SampleAdsWrapper.java

VOD stream Pod Serving

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

// VOD pod stream request.
request = sdkFactory.createPodVodStreamRequest(NETWORK_CODE);
SampleAdsWrapper.java

After you create the stream request instance, request the stream using AdsLoader.requestStream():

request.setFormat(STREAM_FORMAT);
adsLoader.requestStream(request);
SampleAdsWrapper.java

Edit and set the stream URL

Live stream Pod Serving

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

// Play the live pod stream.
streamID = streamManager.getStreamId();
String liveStreamUrl = STREAM_URL.replace("[[STREAMID]]", streamID);
// Call videoPlayer.play() here, because IMA doesn't call the VideoStreamPlayer.loadUrl()
// function for livestreams.
videoPlayer.setStreamUrl(liveStreamUrl);
videoPlayer.play();
SampleAdsWrapper.java

VOD stream Pod Serving

1. Call the StreamManager.getStreamId() method to get the stream ID.
2. Request a stream URL from your video technology partner (VTP).
3. After you receive the URL from your VTP, call the StreamManager.loadThirdPartyStream() method with the URL to load the stream, along with any subtitles your VTP returns.

// Play the VOD pod stream.
streamID = streamManager.getStreamId();
String vodStreamUrl = "";
// Refer to your Video Tech Partner (VTP) or video stitching guide to fetch the stream URL
// and the subtitles for a the ad stitched VOD stream.

// In the following commented out code, 'vtpInterface' is a place holder
// for your own video technology partner (VTP) API calls.
// vodStreamUrl = vtpInterface.requestStreamURL(streamID);
List<Map<String, String>> subtitles = new ArrayList<>();
streamManager.loadThirdPartyStream(vodStreamUrl, subtitles);
SampleAdsWrapper.java

For VOD Pod Serving requests, IMA calls the VideoStreamPlayer.loadUrl() callback when the stream has loaded. To start stream playback, add the videoPlayer.setStreamUrl() and videoPlayer.play() calls to the VideoStreamPlayer.loadUrl() callback:

private VideoStreamPlayer createVideoStreamPlayer() {
  return new VideoStreamPlayer() {
    @Override
    public void loadUrl(String url, List<HashMap<String, String>> subtitles) {
      // IMA doesn't make calls to VideoStreamPlayer.loadUrl() for pod serving live streams.
      // The following code is for VOD streams.
      videoPlayer.setStreamUrl(url);
      videoPlayer.play();
    }
SampleAdsWrapper.java

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 StreamManager.destroy() to stop stream playback, stop all ad tracking, and release all of the loaded stream assets.

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