# ImaAdsLoader

Artifact: [androidx.media3:media3-exoplayer-ima](https://developer.android.com/jetpack/androidx/releases/media3) [View Source](https://cs.android.com/search?q=file:androidx/media3/exoplayer/ima/ImaAdsLoader.java+class:androidx.media3.exoplayer.ima.ImaAdsLoader)

*** ** * ** ***

<br />

```
public final class ImaAdsLoader implements AdsLoader
```

<br />

*** ** * ** ***

`https://developer.android.com/reference/androidx/media3/exoplayer/source/ads/AdsLoader` using the IMA SDK. All methods must be called on the main thread.

The player instance that will play the loaded ads must be set before playback using `https://developer.android.com/reference/androidx/media3/exoplayer/ima/ImaAdsLoader#setPlayer(androidx.media3.common.Player)`. If the ads loader is no longer required, it must be released by calling `https://developer.android.com/reference/androidx/media3/exoplayer/ima/ImaAdsLoader#release()`.

See [IMA's Support and compatibility page](https://developers.google.com/interactive-media-ads/docs/sdks/android/compatibility) for information on compatible ad tag formats. Pass the ad tag URI when setting media item playback properties (if using the media item API) or as a `https://developer.android.com/reference/androidx/media3/datasource/DataSpec` when constructing the `https://developer.android.com/reference/androidx/media3/exoplayer/source/ads/AdsMediaSource` (if using media sources directly). For the latter case, please note that this implementation delegates loading of the data spec to the IMA SDK, so range and headers specifications will be ignored in ad tag URIs. Literal ads responses can be encoded as data scheme data specs, for example, by constructing the data spec using a URI generated via `https://developer.android.com/reference/androidx/media3/common/util/Util#getDataUriForString(java.lang.String,java.lang.String)`.

The IMA SDK can report obstructions to the ad view for accurate viewability measurement. This means that any overlay views that obstruct the ad overlay but are essential for playback need to be registered via the `https://developer.android.com/reference/androidx/media3/common/AdViewProvider` passed to the `https://developer.android.com/reference/androidx/media3/exoplayer/source/ads/AdsMediaSource`. See the [IMA SDK Open Measurement documentation](https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/omsdk) for more information.

## Summary

| ### Nested types |
|---|
| `public final class https://developer.android.com/reference/androidx/media3/exoplayer/ima/ImaAdsLoader.Builder` Builder for `https://developer.android.com/reference/androidx/media3/exoplayer/ima/ImaAdsLoader`. |

| ### Public methods |
|---|---|
| `void` | `@https://developer.android.com/reference/androidx/media3/common/util/UnstableApi https://developer.android.com/reference/androidx/media3/exoplayer/ima/ImaAdsLoader#focusSkipButton()()` Moves UI focus to the skip button (or other interactive elements), if currently shown. |
| `@https://developer.android.com/reference/androidx/annotation/Nullable https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/api/reference/com/google/ads/interactivemedia/v3/api/AdDisplayContainer.html` | `@https://developer.android.com/reference/androidx/media3/common/util/UnstableApi https://developer.android.com/reference/androidx/media3/exoplayer/ima/ImaAdsLoader#getAdDisplayContainer()()` Returns the `https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/api/reference/com/google/ads/interactivemedia/v3/api/AdDisplayContainer.html` used by this loader, or `null` if ads have not been requested yet. |
| `@https://developer.android.com/reference/androidx/annotation/Nullable https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/api/reference/com/google/ads/interactivemedia/v3/api/AdsLoader.html` | `@https://developer.android.com/reference/androidx/media3/common/util/UnstableApi https://developer.android.com/reference/androidx/media3/exoplayer/ima/ImaAdsLoader#getAdsLoader()()` Returns the underlying `https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/api/reference/com/google/ads/interactivemedia/v3/api/AdsLoader.html` wrapped by this instance, or `null` if ads have not been requested yet. |
| `void` | `@https://developer.android.com/reference/androidx/media3/common/util/UnstableApi https://developer.android.com/reference/androidx/media3/exoplayer/ima/ImaAdsLoader#handlePrepareComplete(androidx.media3.exoplayer.source.ads.AdsMediaSource,int,int)( https://developer.android.com/reference/androidx/media3/exoplayer/source/ads/AdsMediaSource adsMediaSource, int adGroupIndex, int adIndexInAdGroup )` Notifies the ads loader that preparation of an ad media period is complete. |
| `void` | `@https://developer.android.com/reference/androidx/media3/common/util/UnstableApi https://developer.android.com/reference/androidx/media3/exoplayer/ima/ImaAdsLoader#handlePrepareError(androidx.media3.exoplayer.source.ads.AdsMediaSource,int,int,java.io.IOException)( https://developer.android.com/reference/androidx/media3/exoplayer/source/ads/AdsMediaSource adsMediaSource, int adGroupIndex, int adIndexInAdGroup, https://developer.android.com/reference/java/io/IOException.html exception )` Notifies the ads loader that the player was not able to prepare media for a given ad. |
| `void` | `https://developer.android.com/reference/androidx/media3/exoplayer/ima/ImaAdsLoader#release()()` Releases the loader. |
| `void` | `@https://developer.android.com/reference/androidx/media3/common/util/UnstableApi https://developer.android.com/reference/androidx/media3/exoplayer/ima/ImaAdsLoader#requestAds(androidx.media3.datasource.DataSpec,java.lang.Object,android.view.ViewGroup)( https://developer.android.com/reference/androidx/media3/datasource/DataSpec adTagDataSpec, https://developer.android.com/reference/java/lang/Object.html adsId, @https://developer.android.com/reference/androidx/annotation/Nullable https://developer.android.com/reference/android/view/ViewGroup.html adViewGroup )` Requests ads, if they have not already been requested. |
| `void` | `https://developer.android.com/reference/androidx/media3/exoplayer/ima/ImaAdsLoader#setPlayer(androidx.media3.common.Player)(@https://developer.android.com/reference/androidx/annotation/Nullable https://developer.android.com/reference/androidx/media3/common/Player player)` Sets the player that will play the loaded ads. |
| `void` | `@https://developer.android.com/reference/androidx/media3/common/util/UnstableApi https://developer.android.com/reference/androidx/media3/exoplayer/ima/ImaAdsLoader#setSupportedContentTypes(int...)(@https://developer.android.com/reference/androidx/media3/common/C.ContentType int[] contentTypes)` Sets the supported content types for ad media. |
| `void` | `@https://developer.android.com/reference/androidx/media3/common/util/UnstableApi https://developer.android.com/reference/androidx/media3/exoplayer/ima/ImaAdsLoader#skipAd()()` Skips the current ad. |
| `void` | `@https://developer.android.com/reference/androidx/media3/common/util/UnstableApi https://developer.android.com/reference/androidx/media3/exoplayer/ima/ImaAdsLoader#start(androidx.media3.exoplayer.source.ads.AdsMediaSource,androidx.media3.datasource.DataSpec,java.lang.Object,androidx.media3.common.AdViewProvider,androidx.media3.exoplayer.source.ads.AdsLoader.EventListener)( https://developer.android.com/reference/androidx/media3/exoplayer/source/ads/AdsMediaSource adsMediaSource, https://developer.android.com/reference/androidx/media3/datasource/DataSpec adTagDataSpec, https://developer.android.com/reference/java/lang/Object.html adsId, https://developer.android.com/reference/androidx/media3/common/AdViewProvider adViewProvider, https://developer.android.com/reference/androidx/media3/exoplayer/source/ads/AdsLoader.EventListener eventListener )` Starts using the ads loader for playback. |
| `void` | `@https://developer.android.com/reference/androidx/media3/common/util/UnstableApi https://developer.android.com/reference/androidx/media3/exoplayer/ima/ImaAdsLoader#stop(androidx.media3.exoplayer.source.ads.AdsMediaSource,androidx.media3.exoplayer.source.ads.AdsLoader.EventListener)( https://developer.android.com/reference/androidx/media3/exoplayer/source/ads/AdsMediaSource adsMediaSource, https://developer.android.com/reference/androidx/media3/exoplayer/source/ads/AdsLoader.EventListener eventListener )` Stops using the ads loader for playback and deregisters the event listener. |

### Inherited methods

From [androidx.media3.exoplayer.source.ads.AdsLoader](https://developer.android.com/reference/androidx/media3/exoplayer/source/ads/AdsLoader) `boolean` `@https://developer.android.com/reference/androidx/media3/common/util/UnstableApi
https://developer.android.com/reference/androidx/media3/exoplayer/source/ads/AdsLoader#handleContentTimelineChanged(androidx.media3.exoplayer.source.ads.AdsMediaSource,androidx.media3.common.Timeline)(

https://developer.android.com/reference/androidx/media3/exoplayer/source/ads/AdsMediaSource adsMediaSource,

https://developer.android.com/reference/androidx/media3/common/Timeline timeline

)`

Notifies the ads loader when the content source has changed its timeline.

## Public methods

### focusSkipButton

```
@UnstableApi
public void focusSkipButton()
```

Moves UI focus to the skip button (or other interactive elements), if currently shown. See `https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/api/reference/com/google/ads/interactivemedia/v3/api/BaseManager.html#focus--`.

### getAdDisplayContainer

```
@UnstableApi
public @Nullable AdDisplayContainer getAdDisplayContainer()
```

Returns the `https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/api/reference/com/google/ads/interactivemedia/v3/api/AdDisplayContainer.html` used by this loader, or `null` if ads have not been requested yet.

Note: any video controls overlays registered via `https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/api/reference/com/google/ads/interactivemedia/v3/api/BaseDisplayContainer.html#registerFriendlyObstruction-com.google.ads.interactivemedia.v3.api.FriendlyObstruction-` will be unregistered automatically when the media source detaches from this instance. It is therefore necessary to re-register views each time the ads loader is reused. Alternatively, provide overlay views via the `https://developer.android.com/reference/androidx/media3/common/AdViewProvider` when creating the media source to benefit from automatic registration.

### getAdsLoader

```
@UnstableApi
public @Nullable AdsLoader getAdsLoader()
```

Returns the underlying `https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/api/reference/com/google/ads/interactivemedia/v3/api/AdsLoader.html` wrapped by this instance, or `null` if ads have not been requested yet.

### handlePrepareComplete

```
@UnstableApi
public void handlePrepareComplete(
    AdsMediaSource adsMediaSource,
    int adGroupIndex,
    int adIndexInAdGroup
)
```

Notifies the ads loader that preparation of an ad media period is complete. Called on the main thread by `https://developer.android.com/reference/androidx/media3/exoplayer/source/ads/AdsMediaSource`.

| Parameters |
|---|---|
| `https://developer.android.com/reference/androidx/media3/exoplayer/source/ads/AdsMediaSource adsMediaSource` | The ads media source for which preparation of ad media completed. |
| `int adGroupIndex` | The index of the ad group. |
| `int adIndexInAdGroup` | The index of the ad in the ad group. |

### handlePrepareError

```
@UnstableApi
public void handlePrepareError(
    AdsMediaSource adsMediaSource,
    int adGroupIndex,
    int adIndexInAdGroup,
    IOException exception
)
```

Notifies the ads loader that the player was not able to prepare media for a given ad. Implementations should update the ad playback state as the specified ad has failed to load. Called on the main thread by `https://developer.android.com/reference/androidx/media3/exoplayer/source/ads/AdsMediaSource`.

| Parameters |
|---|---|
| `https://developer.android.com/reference/androidx/media3/exoplayer/source/ads/AdsMediaSource adsMediaSource` | The ads media source for which preparation of ad media failed. |
| `int adGroupIndex` | The index of the ad group. |
| `int adIndexInAdGroup` | The index of the ad in the ad group. |
| `https://developer.android.com/reference/java/io/IOException.html exception` | The preparation error. |

### release

```
public void release()
```

Releases the loader. Must be called by the application on the main thread when the instance is no longer needed.

### requestAds

```
@UnstableApi
public void requestAds(
    DataSpec adTagDataSpec,
    Object adsId,
    @Nullable ViewGroup adViewGroup
)
```

Requests ads, if they have not already been requested. Must be called on the main thread.

Ads will be requested automatically when the player is prepared if this method has not been called, so it is only necessary to call this method if you want to request ads before preparing the player.

| Parameters |
|---|---|
| `https://developer.android.com/reference/androidx/media3/datasource/DataSpec adTagDataSpec` | The data specification of the ad tag to load. See class javadoc for information about compatible ad tag formats. |
| `https://developer.android.com/reference/java/lang/Object.html adsId` | A opaque identifier for the ad playback state across start/stop calls. |
| `@https://developer.android.com/reference/androidx/annotation/Nullable https://developer.android.com/reference/android/view/ViewGroup.html adViewGroup` | A `https://developer.android.com/reference/android/view/ViewGroup.html` on top of the player that will show any ad UI, or ` null` if playing audio-only ads. |

### setPlayer

```
public void setPlayer(@Nullable Player player)
```

Sets the player that will play the loaded ads.

This method must be called before the player is prepared with media using this ads loader.

This method must also be called on the main thread and only players which are accessed on the main thread are supported (`player.getApplicationLooper() == Looper.getMainLooper()`).

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/Nullable https://developer.android.com/reference/androidx/media3/common/Player player` | The player instance that will play the loaded ads. May be null to delete the reference to a previously set player. |

### setSupportedContentTypes

```
@UnstableApi
public void setSupportedContentTypes(@C.ContentType int[] contentTypes)
```

Sets the supported content types for ad media. Must be called before the first call to `https://developer.android.com/reference/androidx/media3/exoplayer/source/ads/AdsLoader#start(androidx.media3.exoplayer.source.ads.AdsMediaSource,androidx.media3.datasource.DataSpec,java.lang.Object,androidx.media3.common.AdViewProvider,androidx.media3.exoplayer.source.ads.AdsLoader.EventListener)`. Subsequent calls may be ignored. Called on the main thread by `https://developer.android.com/reference/androidx/media3/exoplayer/source/ads/AdsMediaSource`.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/media3/common/C.ContentType int[] contentTypes` | The supported content types for ad media. Each element must be one of `https://developer.android.com/reference/androidx/media3/common/C#CONTENT_TYPE_DASH()`, `https://developer.android.com/reference/androidx/media3/common/C#CONTENT_TYPE_HLS()`, `https://developer.android.com/reference/androidx/media3/common/C#CONTENT_TYPE_SS()` and `https://developer.android.com/reference/androidx/media3/common/C#CONTENT_TYPE_OTHER()`. |

### skipAd

```
@UnstableApi
public void skipAd()
```

Skips the current ad.

This method is intended for apps that play audio-only ads and so need to provide their own UI for users to skip skippable ads. Apps showing video ads should not call this method, as the IMA SDK provides the UI to skip ads in the ad view group passed via `https://developer.android.com/reference/androidx/media3/common/AdViewProvider`.

### start

```
@UnstableApi
public void start(
    AdsMediaSource adsMediaSource,
    DataSpec adTagDataSpec,
    Object adsId,
    AdViewProvider adViewProvider,
    AdsLoader.EventListener eventListener
)
```

Starts using the ads loader for playback. Called on the main thread by `https://developer.android.com/reference/androidx/media3/exoplayer/source/ads/AdsMediaSource`.

Requests the ads loader to start loading ad data from the provided `https://developer.android.com/reference/androidx/media3/datasource/DataSpec`. Publishing an initial `https://developer.android.com/reference/androidx/media3/common/AdPlaybackState` to provided `https://developer.android.com/reference/androidx/media3/exoplayer/source/ads/AdsLoader.EventListener#onAdPlaybackState(androidx.media3.common.AdPlaybackState)` is required to start playback. In the case of a pre roll, this ensures that the player doesn't briefly start playing content before ad data is available.

| Parameters |
|---|---|
| `https://developer.android.com/reference/androidx/media3/exoplayer/source/ads/AdsMediaSource adsMediaSource` | The ads media source requesting to start loading ads. |
| `https://developer.android.com/reference/androidx/media3/datasource/DataSpec adTagDataSpec` | A data spec for the ad tag to load. |
| `https://developer.android.com/reference/java/lang/Object.html adsId` | An opaque identifier for the ad playback state across start/stop calls. |
| `https://developer.android.com/reference/androidx/media3/common/AdViewProvider adViewProvider` | Provider of views for the ad UI. |
| `https://developer.android.com/reference/androidx/media3/exoplayer/source/ads/AdsLoader.EventListener eventListener` | Listener for ads loader events. |

### stop

```
@UnstableApi
public void stop(
    AdsMediaSource adsMediaSource,
    AdsLoader.EventListener eventListener
)
```

Stops using the ads loader for playback and deregisters the event listener. Called on the main thread by `https://developer.android.com/reference/androidx/media3/exoplayer/source/ads/AdsMediaSource`.

| Parameters |
|---|---|
| `https://developer.android.com/reference/androidx/media3/exoplayer/source/ads/AdsMediaSource adsMediaSource` | The ads media source requesting to stop loading/playing ads. |
| `https://developer.android.com/reference/androidx/media3/exoplayer/source/ads/AdsLoader.EventListener eventListener` | The ads media source's listener for ads loader events. |