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 client-side SDKs, you maintain control of content video playback, while the SDK handles ad playback. Ads play in a separate video player positioned on top of the app's content video player.
This guide demonstrates how to integrate the IMA SDK into an empty Android Studio project using the ExoPlayer IMA extension. If you would like to view or follow along with a completed sample integration, download the BasicExample from GitHub.
IMA client-side overview
Implementing IMA client-side involves four main SDK components, which are demonstrated in this guide:
AdDisplayContainer: A container object where ads are rendered.AdsLoader: An object that requests ads and handles events from ads request responses. You should only instantiate one ads loader, which can be reused throughout the life of the application.AdsRequest: An object that defines an ads request. Ads requests specify the URL for the VAST ad tag, as well as additional parameters, such as ad dimensions.AdsManager: An object that contains the response to the ads request, controls ad playback, and listens for ad events fired by the SDK.
Prerequisites
Before you begin, you need Android Studio 3.0 or higher.
1. Create a new Android Studio project
To create your Android Studio project, complete the following steps:
- Start Android Studio.
- Select Start a new Android Studio project.
- In the Choose your project page, select the Empty Activity template.
- Click Next.
- In the Configure your project page, name your project and select Java for the language.
- Click Finish.
2. Add the ExoPlayer IMA extension to your project
First, in the application-level build.gradle file, add imports for the extension to the
dependencies section. Because of the size of the ExoPlayer IMA extension, implement and enable
multidex here. This is necessary for apps with minSdkVersion set to 20 or lower.
Also, add new compileOptions to specify the Java version compatibility information.
android {
namespace 'com.google.ads.interactivemedia.v3.samples.exoplayerexample'
compileSdkVersion 34
compileOptions {
sourceCompatibility JavaVersion.VERSION_17
targetCompatibility JavaVersion.VERSION_17
}
}
defaultConfig {
applicationId "com.google.ads.interactivemedia.v3.samples.exoplayerexample"
minSdkVersion 21
targetSdkVersion 34
multiDexEnabled true
versionCode 1
versionName "1.0"
}
...
}
dependencies {
implementation 'androidx.multidex:multidex:2.0.1'
implementation 'androidx.media3:media3-ui:1.2.1'
implementation 'androidx.media3:media3-exoplayer:1.2.1'
implementation 'androidx.media3:media3-exoplayer-ima:1.2.1'
...
}
Add the user permissions required by the IMA SDK for requesting ads.
app/src/main/AndroidManifest.xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.example.project name">
<!-- Required permissions for the IMA SDK -->
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
...
</manifest>
Add intent declarations
If your app targets Android 11 (API level 30) or higher, the current and recent versions of the IMA SDK require an explicit declaration of intent to open web links. Add the following snippet to your app's manifest file in order to enable ad clickthroughs (users clicking the Learn more button).
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.example.project name">
...
</application>
<queries>
<intent>
<action android:name="android.intent.action.VIEW" />
<data android:scheme="https" />
</intent>
<intent>
<action android:name="android.intent.action.VIEW" />
<data android:scheme="http" />
</intent>
</queries>
</manifest>
3. Create the ad UI container
Create the view to use as the ExoPlayer PlayerView by creating a StyledPlayerView
object with an appropriate ID. Also change the
androidx.constraintlayout.widget.ConstraintLayout to a LinearLayout.
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
xmlns:tools="http://schemas.android.com/tools"
android:layout_width="match_parent"
android:layout_height="match_parent"
tools:context=".MainActivity">
<androidx.media3.ui.PlayerView
android:id="@+id/player_view"
android:layout_width="match_parent"
android:layout_height="wrap_content" />
</LinearLayout>
4. Add your content URL and ad tag URL for the ads request
Add entries to strings.xml to store your content URL and VAST ad tag URL.
<resources>
<string name="app_name">Your_Project_Name</string>
<string name="content_url"><![CDATA[https://storage.googleapis.com/gvabox/media/samples/stock.mp4]]></string>
<string name="ad_tag_url"><![CDATA[https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/single_ad_samples&sz=640x480&cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator=]]></string>
</resources>
5. Import the ExoPlayer IMA extension
Add the import statements for the ExoPlayer extension. Then, update the
MainActivity class to extend Activity by adding private variables for
the PlayerView, SimpleExoPlayer, and ImaAdsLoader.
import android.app.Activity;
import android.net.Uri;
import android.os.Bundle;
import androidx.media3.common.MediaItem;
import androidx.media3.common.util.Util;
import androidx.media3.datasource.DataSource;
import androidx.media3.datasource.DefaultDataSource;
import androidx.media3.exoplayer.ExoPlayer;
import androidx.media3.exoplayer.ima.ImaAdsLoader;
import androidx.media3.exoplayer.source.DefaultMediaSourceFactory;
import androidx.media3.exoplayer.source.MediaSource;
import androidx.media3.ui.PlayerView;
import androidx.multidex.MultiDex;
...
public class MainActivity extends Activity {
private PlayerView playerView;
private ExoPlayer player;
private ImaAdsLoader adsLoader;
}
6. Create an adsLoader instance
Overwrite the onCreate method and add the required variable assignments to create a
new adsLoader object with the ad tag URL.
...
public class MainActivity extends Activity {
private PlayerView playerView;
private ExoPlayer player;
private ImaAdsLoader adsLoader;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
MultiDex.install(this);
playerView = findViewById(R.id.player_view);
// Create an AdsLoader.
adsLoader =
new ImaAdsLoader.Builder(/* context= */ this)
.setAdEventListener(buildAdEventListener())
.build();
}
public AdEvent.AdEventListener buildAdEventListener() {
AdEvent.AdEventListener imaAdEventListener = event -> {
AdEvent.AdEventType eventType = event.getType();
// Log IMA events for debugging.
// The ExoPlayer IMA extension already handles IMA events and does not need anything
// additional here to function.
};
return imaAdEventListener;
}
}
7. Initialize and release the player
Add methods to initialize and release the player. In the initialize
method, create the SimpleExoPlayer. Then, create the AdsMediaSource
and set it to the player.
public class MainActivity extends Activity {
...
private void releasePlayer() {
adsLoader.setPlayer(null);
playerView.setPlayer(null);
player.release();
player = null;
}
private void initializePlayer() {
// Set up the factory for media sources, passing the ads loader and ad view providers.
DataSource.Factory dataSourceFactory = new DefaultDataSource.Factory(this);
MediaSource.Factory mediaSourceFactory =
new DefaultMediaSourceFactory(dataSourceFactory)
.setLocalAdInsertionComponents(unusedAdTagUri -> adsLoader, playerView);
// Create an ExoPlayer and set it as the player for content and ads.
player = new ExoPlayer.Builder(this).setMediaSourceFactory(mediaSourceFactory).build();
playerView.setPlayer(player);
adsLoader.setPlayer(player);
// Create the MediaItem to play, specifying the content URI and ad tag URI.
Uri contentUri = Uri.parse(getString(R.string.content_url));
Uri adTagUri = Uri.parse(getString(R.string.ad_tag_url));
MediaItem mediaItem =
new MediaItem.Builder()
.setUri(contentUri)
.setAdsConfiguration(new MediaItem.AdsConfiguration.Builder(adTagUri).build())
.build();
// Prepare the content and ad to be played with the SimpleExoPlayer.
player.setMediaItem(mediaItem);
player.prepare();
// Set PlayWhenReady. If true, content and ads will autoplay.
player.setPlayWhenReady(false);
}
}
8. Handle player events
Finally, create callbacks for the player's lifecycle events:
onStartonResumeonStoponPauseonDestroy
public class MainActivity extends Activity {
private PlayerView playerView;
private SimpleExoPlayer player;
private ImaAdsLoader adsLoader;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_my);
playerView = findViewById(R.id.player_view);
// Create an AdsLoader.
adsLoader =
new ImaAdsLoader.Builder(/* context= */ this)
.setAdEventListener(buildAdEventListener())
.build();
}
@Override
public void onStart() {
super.onStart();
//
if (Util.SDK_INT > 23) {
initializePlayer();
if (playerView != null) {
playerView.onResume();
}
}
}
@Override
public void onResume() {
super.onResume();
if (Util.SDK_INT <= 23 || player == null) {
initializePlayer();
if (playerView != null) {
playerView.onResume();
}
}
}
@Override
public void onPause() {
super.onPause();
if (Util.SDK_INT <= 23) {
if (playerView != null) {
playerView.onPause();
}
releasePlayer();
}
}
@Override
public void onStop() {
super.onStop();
if (Util.SDK_INT > 23) {
if (playerView != null) {
playerView.onPause();
}
releasePlayer();
}
}
@Override
protected void onDestroy() {
super.onDestroy();
adsLoader.release();
}
...
}
That's it! You're now requesting and displaying ads with the IMA SDK. To learn about additional SDK features, see the other guides or the samples on GitHub.