Select platform: [HTML5](https://developers.google.com/ad-manager/dynamic-ad-insertion/sdk/html5/get-started/full-service.md.txt "View this page for the HTML5 platform docs.") [Android](https://developers.google.com/ad-manager/dynamic-ad-insertion/sdk/android/get-started/full-service.md.txt "View this page for the Android platform docs.") [iOS](https://developers.google.com/ad-manager/dynamic-ad-insertion/sdk/ios/get-started/full-service.md.txt "View this page for the iOS platform docs.") [tvOS](https://developers.google.com/ad-manager/dynamic-ad-insertion/sdk/tvos/get-started/full-service.md.txt "View this page for the tvOS platform docs.") [Cast](https://developers.google.com/ad-manager/dynamic-ad-insertion/sdk/cast/get-started/full-service.md.txt "View this page for the Cast platform docs.") [Roku](https://developers.google.com/ad-manager/dynamic-ad-insertion/sdk/roku/get-started/full-service.md.txt "View this page for the Roku platform docs.")
This guide demonstrates how to integrate the IMA DAI SDK into a simple video player
app. If you would like to view or follow along with a completed sample
integration, download the [BasicExample](https://github.com/googleads/googleads-ima-android-dai) from
GitHub.
**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](https://github.com/googleads/googleads-ima-android-dai/blob/main/AdvancedExample/app/src/main/java/com/google/ads/interactivemedia/v3/samples/samplevideoplayer/SampleVideoPlayer.java#L151-L166).
> [!IMPORTANT]
> To use IMA DAI, you must have an [Ad Manager 360 Advanced](https://support.google.com/admanager/answer/3485387) 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](https://support.google.com/admanager/answer/7084151).
> [!IMPORTANT]
> **Key Point:** The [ExoPlayer IMA
> extension](https://github.com/google/ExoPlayer/tree/release-v2/extensions/ima) offers a streamlined way to use IMA DAI on Android. See the [ExoPlayer IMA extension
> guide](https://developers.google.com/ad-manager/dynamic-ad-insertion/sdk/android/exoplayer-extension) and the [ExoPlayerExample on GitHub](https://github.com/googleads/googleads-ima-android-dai) for more details.
**Note:** 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).
## IMA DAI overview
Implementing IMA DAI involves four main SDK components as demonstrated in this
guide:
- `
StreamDisplayContainer`: A container object that sits on top of the video playback element and houses the ad UI elements.
- `
AdsLoader`: An object that requests streams and handles events triggered by stream request response objects. You should only instantiate one ads loader, which can be reused throughout the life of the application.
- `
StreamRequest`: An object that defines a stream request. Stream requests can either be for video-on-demand or live streams. Live stream requests specify an asset key, while VOD requests specify a CMS ID and video ID. Both request types can optionally include an API key needed to access specified streams, and a Google Ad Manager network code for the IMA SDK to handle ads identifiers as specified in Google Ad Manager settings.
- `
StreamManager`: An object that handles dynamic ad insertion streams and interactions with the DAI backend. The stream manager also handles tracking pings and forwards stream and ad events to the publisher.
## Prerequisites
- [Android Studio](https://developer.android.com/studio)
- Sample video player app for the SDK integration
## Download and run the sample video player app
The sample app provides a working video player that plays HLS video. Use this as
a starting point for integrating the IMA DAI SDK's DAI capabilities.
1. Download the [sample video player
app](https://github.com/googleads/googleads-ima-android-dai/releases/latest) and
extract it.
2. Start Android Studio and select **Open an existing Android Studio project** ,
or if Android Studio is already running, select **File \> New \> Import
Project** . Then choose `SampleVideoPlayer/build.gradle`.
3. Run a Gradle sync by selecting **Tools \> Android \> Sync Project with Gradle Files**.
4. Ensure that the player app compiles and runs on a physical Android device or
an Android Virtual Device using **Run \> Run 'app'**. It's normal for the video
stream to take a few moments to load before playing.
> [!TIP]
> **Tip:** If you're new to developing Android applications, take a look at the tutorials for [USB Debugging](https://developer.android.com/tools/device.html) and [Using Virtual Devices](https://developer.android.com/tools/devices/emulator.html). You need to do one of those two things in order to run your new app and see what it looks like.
## Examine the sample video player
The sample video player doesn't contain any IMA DAI SDK integration code yet.
The sample app consists of two major parts:
1. `samplevideoplayer/SampleVideoPlayer.java`: An
[ExoPlayer](https://github.com/google/ExoPlayer)-based HLS player that serves as
the basis for IMA DAI integration.
2. `videoplayerapp/MyActivity.java`: This activity creates the video player and
passes it a `Context` and `media3.ui.PlayerView`.
## Add the IMA DAI SDK to the player app
You must also include a reference to the IMA DAI SDK. In Android Studio, add the
following to your application-level **build.gradle** file, located at
**app/build.gradle** . The IMA SDK requires library desugaring enabled, which you
must do by setting `coreLibraryDesugaringEnabled true` and adding
`'com.android.tools:desugar_jdk_libs'` as a dependency in the **build.gradle**
file. For details, see
[Java 11+ APIs available through desugaring with the nio specification](https://developer.android.com/studio/write/java11-nio-support-table).
```groovy
repositories {
google()
mavenCentral()
}
dependencies {
def media3_version = "1.11.0"
coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
implementation(platform("org.jetbrains.kotlin:kotlin-bom:2.3.21"))
implementation("androidx.appcompat:appcompat:1.8.0")
implementation("androidx.media3:media3-ui:$media3_version")
implementation("androidx.media3:media3-exoplayer:$media3_version")
implementation("androidx.media3:media3-exoplayer-hls:$media3_version")
implementation("androidx.media3:media3-exoplayer-dash:$media3_version")
implementation("androidx.mediarouter:mediarouter:1.8.1")
implementation("com.google.ads.interactivemedia.v3:interactivemedia:3.40.0")
}
```
> [!IMPORTANT]
> **Key Point:** Your app should compile and run at this point, though you've yet to add UI elements or code to request and display ads.
## Integrate the IMA DAI SDK
1. Create a new class called `SampleAdsWrapper` in the `videoplayerapp` package
(in `app/java/com.google.ads.interactivemedia.v3.samples/videoplayerapp/`) to
wrap the existing `SampleVideoPlayer` and add logic implementing IMA DAI. To
do this, you must first create an `AdsLoader` which is used to request the
DAI stream.
This snippet includes sample parameters for HLS and DASH, live and VOD
streams. To set which stream is being played, update the `CONTENT_TYPE`
variable.
```java
package com.google.ads.interactivemedia.v3.samples.videoplayerapp;
import android.annotation.SuppressLint;
import android.content.Context;
import android.view.ViewGroup;
import android.webkit.WebView;
import androidx.annotation.Nullable;
import com.google.ads.interactivemedia.v3.api.AdErrorEvent;
import com.google.ads.interactivemedia.v3.api.AdEvent;
import com.google.ads.interactivemedia.v3.api.AdsLoader;
import com.google.ads.interactivemedia.v3.api.AdsManagerLoadedEvent;
import com.google.ads.interactivemedia.v3.api.CuePoint;
import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
import com.google.ads.interactivemedia.v3.api.StreamDisplayContainer;
import com.google.ads.interactivemedia.v3.api.StreamManager;
import com.google.ads.interactivemedia.v3.api.StreamRequest;
import com.google.ads.interactivemedia.v3.api.StreamRequest.StreamFormat;
import com.google.ads.interactivemedia.v3.api.player.VideoProgressUpdate;
import com.google.ads.interactivemedia.v3.api.player.VideoStreamPlayer;
import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer;
import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer.SampleVideoPlayerCallback;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
/** This class adds ad-serving support to Sample HlsVideoPlayer */
@SuppressLint("UnsafeOptInUsageError")
/* @SuppressLint is needed for new media3 APIs. */
public class SampleAdsWrapper
implements AdEvent.AdEventListener, AdErrorEvent.AdErrorListener, AdsLoader.AdsLoadedListener {
// Live HLS stream asset key.
private static final String TEST_HLS_ASSET_KEY = "c-rArva4ShKVIAkNfy6HUQ";
// Live DASH stream asset key.
private static final String TEST_DASH_ASSET_KEY = "PSzZMzAkSXCmlJOWDmRj8Q";
// VOD HLS content source and video IDs.
private static final String TEST_HLS_CONTENT_SOURCE_ID = "2548831";
private static final String TEST_HLS_VIDEO_ID = "tears-of-steel";
// VOD DASH content source and video IDs.
private static final String TEST_DASH_CONTENT_SOURCE_ID = "2559737";
private static final String TEST_DASH_VIDEO_ID = "tos-dash";
private static final String NETWORK_CODE = "21775744923";
private static final String PLAYER_TYPE = "DAISamplePlayer";
private enum ContentType {
LIVE_HLS,
LIVE_DASH,
VOD_HLS,
VOD_DASH,
}
// Set CONTENT_TYPE to the associated enum for the stream type you would like to test.
private static final ContentType CONTENT_TYPE = ContentType.VOD_HLS;
/** Log interface, so we can output the log commands to the UI or similar. */
public interface Logger {
void log(String logMessage);
}
private final ImaSdkFactory sdkFactory;
private AdsLoader adsLoader;
private StreamManager streamManager;
private final List playerCallbacks;
private final SampleVideoPlayer videoPlayer;
private final Context context;
private final ViewGroup adUiContainer;
private String fallbackUrl;
private Logger logger;
/**
* Creates a new SampleAdsWrapper that implements IMA direct-ad-insertion.
*
* @param context the app's context.
* @param videoPlayer underlying HLS video player.
* @param adUiContainer ViewGroup in which to display the ad's UI.
*/
public SampleAdsWrapper(Context context, SampleVideoPlayer videoPlayer, ViewGroup adUiContainer) {
this.videoPlayer = videoPlayer;
this.context = context;
this.adUiContainer = adUiContainer;
sdkFactory = ImaSdkFactory.getInstance();
playerCallbacks = new ArrayList<>();
createAdsLoader();
}
private void enableWebViewDebugging() {
WebView.setWebContentsDebuggingEnabled(true);
}
private void createAdsLoader() {
enableWebViewDebugging();
VideoStreamPlayer videoStreamPlayer = createVideoStreamPlayer();
StreamDisplayContainer displayContainer =
ImaSdkFactory.createStreamDisplayContainer(adUiContainer, videoStreamPlayer);
videoPlayer.setSampleVideoPlayerCallback(createSampleVideoPlayerCallback());
adsLoader =
sdkFactory.createAdsLoader(context, MyActivity.getImaSdkSettings(), displayContainer);
}
public void requestAndPlayAds() {
adsLoader.addAdErrorListener(this);
adsLoader.addAdsLoadedListener(this);
adsLoader.requestStream(buildStreamRequest());
}
```
2. Create a `createSampleVideoPlayerCallback()` helper method to handle creating
a `SampleVideoPlayerCallback` interface instance which extends
[`VideoStreamPlayer.VideoStreamPlayerCallback`](https://developers.google.com/ad-manager/dynamic-ad-insertion/sdk/android/api/reference/com/google/ads/interactivemedia/v3/api/player/VideoStreamPlayer.VideoStreamPlayerCallback.md.txt).
To work with DAI, the player must pass ID3 events to the IMA DAI SDK. The
`callback.onUserTextReceived()` method does this, in the following sample
code.
```java
private SampleVideoPlayerCallback createSampleVideoPlayerCallback() {
return new SampleVideoPlayerCallback() {
@Override
public void onUserTextReceived(String userText) {
for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
callback.onUserTextReceived(userText);
}
}
@Override
public void onSeek(int windowIndex, long positionMs) {
// See if we would seek past an ad, and if so, jump back to it.
long newSeekPositionMs = positionMs;
if (streamManager != null) {
CuePoint prevCuePoint = streamManager.getPreviousCuePointForStreamTimeMs(positionMs);
if (prevCuePoint != null && !prevCuePoint.isPlayed()) {
newSeekPositionMs = prevCuePoint.getStartTimeMs();
}
}
videoPlayer.seekTo(windowIndex, newSeekPositionMs);
}
@Override
public void onContentComplete() {
for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
callback.onContentComplete();
}
}
@Override
public void onPause() {
for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
callback.onPause();
}
}
@Override
public void onResume() {
for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
callback.onResume();
}
}
@Override
public void onVolumeChanged(int percentage) {
for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
callback.onVolumeChanged(percentage);
}
}
};
}
```
3. Add a `buildStreamRequest()` method to create the `SteamRequest`. This
method switches between different streams based on how you set the
`CONTENT_TYPE` variable. The default stream used in this guide is IMA's
sample VOD HLS stream.
```java
@Nullable
private StreamRequest buildStreamRequest() {
StreamRequest request;
switch (CONTENT_TYPE) {
case LIVE_HLS:
// Live HLS stream request.
return sdkFactory.createLiveStreamRequest(TEST_HLS_ASSET_KEY, null, NETWORK_CODE);
case LIVE_DASH:
// Live DASH stream request.
return sdkFactory.createLiveStreamRequest(TEST_DASH_ASSET_KEY, null, NETWORK_CODE);
case VOD_HLS:
// VOD HLS request.
request =
sdkFactory.createVodStreamRequest(
TEST_HLS_CONTENT_SOURCE_ID, TEST_HLS_VIDEO_ID, null, NETWORK_CODE);
request.setFormat(StreamFormat.HLS);
return request;
case VOD_DASH:
// VOD DASH request.
request =
sdkFactory.createVodStreamRequest(
TEST_DASH_CONTENT_SOURCE_ID, TEST_DASH_VIDEO_ID, null, NETWORK_CODE);
request.setFormat(StreamFormat.DASH);
return request;
}
// Content type not selected.
return null;
}
```
4. You also need a `VideoStreamPlayer` to play the stream, so add a
`createVideoStreamPlayer()` method, which creates an anonymous class that
implements `VideoStreamPlayer`.
```java
private VideoStreamPlayer createVideoStreamPlayer() {
return new VideoStreamPlayer() {
@Override
public void loadUrl(String url, List> subtitles) {
videoPlayer.setStreamUrl(url);
videoPlayer.play();
}
@Override
public void pause() {
// Pause player.
videoPlayer.pause();
}
@Override
public void resume() {
// Resume player.
videoPlayer.play();
}
@Override
public int getVolume() {
// Make the video player play at the current device volume.
return 100;
}
@Override
public void addCallback(VideoStreamPlayerCallback videoStreamPlayerCallback) {
playerCallbacks.add(videoStreamPlayerCallback);
}
@Override
public void removeCallback(VideoStreamPlayerCallback videoStreamPlayerCallback) {
playerCallbacks.remove(videoStreamPlayerCallback);
}
@Override
public void onAdBreakStarted() {
// Disable player controls.
videoPlayer.enableControls(false);
log("Ad Break Started\n");
}
@Override
public void onAdBreakEnded() {
// Re-enable player controls.
if (videoPlayer != null) {
videoPlayer.enableControls(true);
}
log("Ad Break Ended\n");
}
@Override
public void onAdPeriodStarted() {
log("Ad Period Started\n");
}
@Override
public void onAdPeriodEnded() {
log("Ad Period Ended\n");
}
@Override
public void seek(long timeMs) {
// An ad was skipped. Skip to the content time.
videoPlayer.seekTo(timeMs);
log("seek");
}
@Override
public VideoProgressUpdate getContentProgress() {
return new VideoProgressUpdate(
videoPlayer.getCurrentPositionMs(), videoPlayer.getDuration());
}
};
}
```
5. Implement the required listeners and add support for error handling.
Note the `AdErrorListener` implementation, as it calls a fallback URL if the
ads fail to play. Since the content and ads are in one stream, you must be
ready to call a fallback stream if the DAI stream encounters an error.
```java
/** AdErrorListener implementation */
@Override
public void onAdError(AdErrorEvent event) {
log(String.format("Error: %s\n", event.getError().getMessage()));
// play fallback URL.
log("Playing fallback Url\n");
videoPlayer.setStreamUrl(fallbackUrl);
videoPlayer.enableControls(true);
videoPlayer.play();
}
/** AdEventListener implementation */
@Override
public void onAdEvent(AdEvent event) {
switch (event.getType()) {
case AD_PROGRESS:
// Do nothing or else log will be filled by these messages.
break;
default:
log(String.format("Event: %s\n", event.getType()));
break;
}
}
/** AdsLoadedListener implementation */
@Override
public void onAdsManagerLoaded(AdsManagerLoadedEvent event) {
streamManager = event.getStreamManager();
streamManager.addAdErrorListener(this);
streamManager.addAdEventListener(this);
streamManager.init();
}
/** Sets fallback URL in case ads stream fails. */
void setFallbackUrl(String url) {
fallbackUrl = url;
}
```
6. Add in code for logging.
```java
/** Sets logger for displaying events to screen. Optional. */
void setLogger(Logger logger) {
this.logger = logger;
}
private void log(String message) {
if (logger != null) {
logger.log(message);
}
}
```
7. Modify `MyActivity` in `videoplayerapp` to instantiate and call
`SampleAdsWrapper`. Also, make a call to `ImaSdkFactory.initialize()` here
using a helper method to create an `ImaSdkSettings` instance.
**Important:** To improve IMA load times, call the [`ImaSdkFactory.initialize()`](https://developers.google.com/ad-manager/dynamic-ad-insertion/sdk/android/api/reference/com/google/ads/interactivemedia/v3/api/ImaSdkFactory.md.txt#initialize(android.content.Context,com.google.ads.interactivemedia.v3.api.ImaSdkSettings)) method as early as possible in the app lifecycle. Calling the method early maximizes the time for IMA to load necessary resources before the first stream request. The `ImaSdkFactory.initialize()` method call accepts an `ImaSdkSettings` instance. Make sure to use the same settings values here, and when you create an `AdsLoader` instance. This example uses the `getImaSdkSettings()` helper method to ensure the settings values are the same. For more information, see the [Optimize IMA load time guide\>](https://developers.google.com/ad-manager/dynamic-ad-insertion/sdk/android/load-time.md.txt).
```java
package com.google.ads.interactivemedia.v3.samples.videoplayerapp;
import android.annotation.SuppressLint;
import android.app.Activity;
import android.content.res.Configuration;
import android.os.Bundle;
import android.util.Log;
import android.view.View;
import android.widget.ImageButton;
import android.widget.ScrollView;
import android.widget.TextView;
import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
import com.google.ads.interactivemedia.v3.api.ImaSdkSettings;
import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer;
/** Main Activity that plays media using {@link SampleVideoPlayer}. */
@SuppressLint("UnsafeOptInUsageError")
/* @SuppressLint is needed for new media3 APIs. */
public class MyActivity extends Activity {
private static final String DEFAULT_STREAM_URL =
"https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8";
private static final String APP_LOG_TAG = "ImaDaiExample";
private static final String PLAYER_TYPE = "DAISamplePlayer";
private static ImaSdkSettings imaSdkSettings;
protected SampleVideoPlayer sampleVideoPlayer;
protected ImageButton playButton;
private boolean contentHasStarted = false;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_my);
// Initialize the IMA SDK as early as possible when the app starts. If your app already
// overrides Application.onCreate(), call this method inside the onCreate() method.
// https://developer.android.com/topic/performance/vitals/launch-time#app-creation
ImaSdkFactory.getInstance().initialize(this, getImaSdkSettings());
View rootView = findViewById(R.id.videoLayout);
sampleVideoPlayer =
new SampleVideoPlayer(rootView.getContext(), rootView.findViewById(R.id.playerView));
sampleVideoPlayer.enableControls(false);
playButton = rootView.findViewById(R.id.playButton);
final SampleAdsWrapper sampleAdsWrapper =
new SampleAdsWrapper(this, sampleVideoPlayer, rootView.findViewById(R.id.adUiContainer));
sampleAdsWrapper.setFallbackUrl(DEFAULT_STREAM_URL);
final ScrollView scrollView = findViewById(R.id.logScroll);
final TextView textView = findViewById(R.id.logText);
sampleAdsWrapper.setLogger(
logMessage -> {
Log.i(APP_LOG_TAG, logMessage);
if (textView != null) {
textView.append(logMessage);
}
if (scrollView != null) {
scrollView.post(() -> scrollView.fullScroll(View.FOCUS_DOWN));
}
});
// Set up play button listener to play video then hide play button.
playButton.setOnClickListener(
view -> {
if (contentHasStarted) {
sampleVideoPlayer.play();
} else {
contentHasStarted = true;
sampleVideoPlayer.enableControls(true);
sampleAdsWrapper.requestAndPlayAds();
}
playButton.setVisibility(View.GONE);
});
orientVideoDescription(getResources().getConfiguration().orientation);
}
```
8. Add the `getImaSdkSettings()` helper method to create an `ImaSdkSettings`
instance.
```java
public static ImaSdkSettings getImaSdkSettings() {
if (imaSdkSettings == null) {
imaSdkSettings = ImaSdkFactory.getInstance().createImaSdkSettings();
imaSdkSettings.setPlayerType(PLAYER_TYPE);
// Set any additional IMA SDK settings here.
}
return imaSdkSettings;
}
```
9. Modify the Activity's layout file `activity_my.xml` to add UI elements for
logging.
```xml
```
Congrats! You're now requesting and displaying video ads in your Android
app. To fine tune your implementation, see
[Bookmarks](https://developers.google.com/ad-manager/dynamic-ad-insertion/sdk/android/bookmarks.md.txt),
[Snapback](https://developers.google.com/ad-manager/dynamic-ad-insertion/sdk/android/snapback.md.txt),
and the [API
documentation](https://developers.google.com/ad-manager/dynamic-ad-insertion/sdk/android/api/reference/com/google/ads/interactivemedia/v3/api/package-summary).
## Troubleshooting
If you're experiencing issues playing a video ad, try downloading the completed
[BasicExample](https://github.com/googleads/googleads-ima-android-dai/releases/latest).
If it works properly in the BasicExample then there's likely an issue with your
app's IMA integration code.
If you're still having issues, visit the [IMA SDK
forum](https://groups.google.com/forum/#!forum/ima-sdk).