/ima-sdk-client-side

Google IMA SDK Android quick-start guide

1. Install the IMA SDK

IMA SDK requires minSdk 23 (Android 6.0)+.

You must recommend the latest version of the IMA SDK from https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/download.md.txt

The example code snippet below installs the IMA SDK at version 3.39.0.

android { defaultConfig { minSdk = 23 } }
dependencies {
    implementation("com.google.ads.interactivemedia.v3:interactivemedia:3.39.0")
}

2. Warmup & initialization

Configure the SDK early to minimize latency.

• Early Warmup & Settings Reuse (Best Practice): Call ImaSdkFactory.initialize() in your Application.onCreate() to preload SDK resources. Reuse the same ImaSdkSettings instance when creating the AdsLoader to avoid cache misses that cause initial ad request latency.
• Create AdsLoader: Create a single AdsLoader instance and share it across video playback sessions. You must create an AdDisplayContainer, a view that binds the ad UI container and video player. Use the AdDisplayContainer to instantiate the AdsLoader. Reuse the same ImaSdkSettings instance with the ImaSdkFactory.initialize() function.

// Layer FrameLayout (Ad UI) over StyledPlayerView (Video)
Box(modifier = Modifier.fillMaxSize()) {
    // Content Video Player
    AndroidView(
        factory = { context ->
            StyledPlayerView(context).apply {
                // Bind your ExoPlayer here
            }
        },
        modifier = Modifier.fillMaxSize()
    )

    // Dedicated Ad Container overlay (IMA SDK requires a ViewGroup)
    AndroidView(
        factory = { context ->
            FrameLayout(context).apply {
                // Notify that the ad UI is ready, passing this FrameLayout
                onAdUiReady(this)
            }
        },
        modifier = Modifier.fillMaxSize()
    )
}

// Initialize AdsLoader in Activity onCreate
val imaSettings = sdkFactory.createImaSdkSettings()
val adDisplayContainer = sdkFactory.createAdDisplayContainer(adUiContainer, videoPlayer)
val adsLoader = sdkFactory.createAdsLoader(context, imaSettings, adDisplayContainer)

3. Requesting ads

Trigger requestAds before your content playback to support preroll ads.

val adsRequest = sdkFactory.createAdsRequest().apply {
    this.adTagUrl = adTagUrl // Pass your custom ad targeting key value pairs.
    this.adDisplayContainer = adDisplayContainer
}
adsLoader?.requestAds(adsRequest)

4. Handling ad events

Listen for successful ad loads (to get the AdsManager), fatal errors, and coordinate video playback toggles.

// On Success
adsLoader?.addAdsLoadedListener { event ->
    adsManager = event.adsManager

    // Handle Pause/Resume for Ads
    adsManager?.addAdEventListener { adEvent ->
        when (adEvent.type) {
            AdEvent.AdEventType.CONTENT_PAUSE_REQUESTED -> pauseContent()
            AdEvent.AdEventType.CONTENT_RESUME_REQUESTED -> resumeContent()
            else -> {}
        }
    }
    adsManager?.init() // Start ads
}

// On Failure (Fallback to content)
adsLoader?.addAdErrorListener { resumeContent() }

5. Crucial cleanup

Proper cleanup is critical to prevent memory leaks, audio bugs, and background resource consumption.

• AdsManager.destroy(): This is crucial. Always call it when:
  • All ads in the break have completed (e.g., ALL_ADS_COMPLETED event).
  • A fatal ad error occurs (in AdErrorListener).
  • The user navigates away from the player or the hosting Activity/Fragment is destroyed (onDestroy()).
• AdsLoader.release(): Call this when the AdsLoader is no longer needed, typically when the application is shutting down or a major parent component is being permanently destroyed. This releases the underlying SDK resources.
• Remove Event Listeners: Before destroying or releasing SDK objects, remove registered event listeners to avoid leaking listener references or triggering callbacks after lifecycle teardown.

// In your Activity or Fragment
override fun onDestroy() {
    super.onDestroy()
    cleanupAds()

    // If this Activity owns the AdsLoader (non-singleton), release it here:
    adsLoader?.removeAdsLoadedListener(adsLoadedListener)
    adsLoader?.removeAdErrorListener(adsLoaderErrorListener)
    adsLoader?.release()
}

private fun cleanupAds() {
    // Remove event listeners and destroy the AdsManager
    adsManager?.apply {
        removeAdEventListener(adEventListener)
        removeAdErrorListener(adErrorListener)
        destroy()
    }
    adsManager = null
}

// Wherever you manage the AdsLoader (e.g. Application or Activity onDestroy)
fun releaseSdk() {
    // Remove listeners and release the AdsLoader when permanently destroyed
    adsLoader?.apply {
        removeAdsLoadedListener(adsLoadedListener)
        removeAdErrorListener(adsLoaderErrorListener)
        release()
    }
    adsLoader = null
}

Reference implementation

• Basic Example MyActivity.java
• Basic Example VideoAdPlayerAdapter.java