# AdsLoader

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

*** ** * ** ***

<br />

```
interface AdsLoader
```

<br />

Known direct subclasses [FakeAdsLoader](https://developer.android.com/reference/kotlin/androidx/media3/test/utils/FakeAdsLoader), [HlsInterstitialsAdsLoader](https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/hls/HlsInterstitialsAdsLoader), [ImaAdsLoader](https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/ima/ImaAdsLoader)

|---|---|
| `https://developer.android.com/reference/kotlin/androidx/media3/test/utils/FakeAdsLoader` | A fake implementation of `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsLoader`. |
| `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/hls/HlsInterstitialsAdsLoader` | An `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsLoader` that reads interstitials from the HLS playlist, adds them to the `https://developer.android.com/reference/kotlin/androidx/media3/common/AdPlaybackState` and passes the ad playback state to `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsLoader.EventListener#onAdPlaybackState(androidx.media3.common.AdPlaybackState)`. |
| `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/ima/ImaAdsLoader` | `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsLoader` using the IMA SDK. |

*** ** * ** ***

Interface for loaders of ads, which can be used with `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsMediaSource`.

Ads loaders notify the `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsMediaSource` about events via `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsLoader.EventListener`. In particular, implementations must call `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsLoader.EventListener#onAdPlaybackState(androidx.media3.common.AdPlaybackState)` with a new copy of the current `https://developer.android.com/reference/kotlin/androidx/media3/common/AdPlaybackState` whenever further information about ads becomes known (for example, when an ad media URI is available, or an ad has played to the end).

`https://developer.android.com/reference/kotlin/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)` will be called when an ads media source first initializes, at which point the loader can request ads. If the player enters the background, `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsLoader#stop(androidx.media3.exoplayer.source.ads.AdsMediaSource,androidx.media3.exoplayer.source.ads.AdsLoader.EventListener)` will be called. Loaders should maintain any ad playback state in preparation for a later call to `https://developer.android.com/reference/kotlin/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)`. If an ad is playing when the player is detached, update the ad playback state with the current playback position using `https://developer.android.com/reference/kotlin/androidx/media3/common/AdPlaybackState#withAdResumePositionUs(long)`.

If `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsLoader.EventListener#onAdPlaybackState(androidx.media3.common.AdPlaybackState)` has been called, the implementation of `https://developer.android.com/reference/kotlin/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)` should invoke the same listener to provide the existing playback state to the new player.

## Summary

| ### Nested types |
|---|
| `@https://developer.android.com/reference/kotlin/androidx/media3/common/util/UnstableApi interface https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsLoader.EventListener` Listener for ads loader events. |
| `interface https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsLoader.Provider` Provides `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsLoader` instances for media items that have `https://developer.android.com/reference/kotlin/androidx/media3/common/MediaItem.LocalConfiguration#adsConfiguration()`. |

| ### Public functions |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `@https://developer.android.com/reference/kotlin/androidx/media3/common/util/UnstableApi https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsLoader#handleContentTimelineChanged(androidx.media3.exoplayer.source.ads.AdsMediaSource,androidx.media3.common.Timeline)( adsMediaSource: https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsMediaSource!, timeline: https://developer.android.com/reference/kotlin/androidx/media3/common/Timeline! )` Notifies the ads loader when the content source has changed its timeline. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/media3/common/util/UnstableApi https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsLoader#handlePrepareComplete(androidx.media3.exoplayer.source.ads.AdsMediaSource,int,int)( adsMediaSource: https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsMediaSource!, adGroupIndex: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, adIndexInAdGroup: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html )` Notifies the ads loader that preparation of an ad media period is complete. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/media3/common/util/UnstableApi https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsLoader#handlePrepareError(androidx.media3.exoplayer.source.ads.AdsMediaSource,int,int,java.io.IOException)( adsMediaSource: https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsMediaSource!, adGroupIndex: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, adIndexInAdGroup: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, exception: https://developer.android.com/reference/java/io/IOException.html! )` Notifies the ads loader that the player was not able to prepare media for a given ad. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsLoader#release()()` Releases the loader. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsLoader#setPlayer(androidx.media3.common.Player)(player: https://developer.android.com/reference/kotlin/androidx/media3/common/Player?)` Sets the player that will play the loaded ads. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/media3/common/util/UnstableApi https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsLoader#setSupportedContentTypes(int...)(@https://developer.android.com/reference/kotlin/androidx/media3/common/C.ContentType contentTypes: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int-array/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html>!)` Sets the supported content types for ad media. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/media3/common/util/UnstableApi https://developer.android.com/reference/kotlin/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)( adsMediaSource: https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsMediaSource!, adTagDataSpec: https://developer.android.com/reference/kotlin/androidx/media3/datasource/DataSpec!, adsId: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html!, adViewProvider: https://developer.android.com/reference/kotlin/androidx/media3/common/AdViewProvider!, eventListener: https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsLoader.EventListener! )` Starts using the ads loader for playback. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/media3/common/util/UnstableApi https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsLoader#stop(androidx.media3.exoplayer.source.ads.AdsMediaSource,androidx.media3.exoplayer.source.ads.AdsLoader.EventListener)( adsMediaSource: https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsMediaSource!, eventListener: https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsLoader.EventListener! )` Stops using the ads loader for playback and deregisters the event listener. |

## Public functions

### handleContentTimelineChanged

```
@UnstableApi
fun handleContentTimelineChanged(
    adsMediaSource: AdsMediaSource!,
    timeline: Timeline!
): Boolean
```

Notifies the ads loader when the content source has changed its timeline. Called on the main thread by `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsMediaSource`.

The default implementation returns false which makes the content timeline immediately being reported to the player.

When overriding this method for the purpose of reading ad data from the timeline to populate the `https://developer.android.com/reference/kotlin/androidx/media3/common/AdPlaybackState` with, false needs to be passed to the constructor of `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsMediaSource#AdsMediaSource(androidx.media3.exoplayer.source.MediaSource,androidx.media3.datasource.DataSpec,java.lang.Object,androidx.media3.exoplayer.source.MediaSource.Factory,androidx.media3.exoplayer.source.ads.AdsLoader,androidx.media3.common.AdViewProvider,boolean,boolean)` to indicate that the content source needs to be prepared upfront. This way an ads loader can defer calling `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsLoader.EventListener#onAdPlaybackState(androidx.media3.common.AdPlaybackState)` until the ad data from the timeline is available and populate the initial ad playback state with that data before publishing.

For live streams, this method is called additional times when the content source reports an advancing `https://developer.android.com/reference/kotlin/androidx/media3/common/Timeline` with new available media and/or new ad data in the manifest. If in such a case, the ads loader as a result calls `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsLoader.EventListener#onAdPlaybackState(androidx.media3.common.AdPlaybackState)`, true must be returned. This prevents the timeline being reported with stale ad data. Conversely, when the ad playback state is not passed into `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsLoader.EventListener#onAdPlaybackState(androidx.media3.common.AdPlaybackState)`, false must be returned to not drop a timeline update that needs to be published to the player.

Generally, if the timeline is not required to populate the ad playback state, `https://developer.android.com/reference/kotlin/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)` should be used to initiate loading ad data and publish the first ad playback state as early as possible. This method can still be overridden for informational or other purpose. In this case, false is returned here and the `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsMediaSource` is used with lazy preparation enabled.

| Parameters |
|---|---|
| `adsMediaSource: https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsMediaSource!` | The ads media source for which the content timeline changed. |
| `timeline: https://developer.android.com/reference/kotlin/androidx/media3/common/Timeline!` | The timeline of the content source. |

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | true If `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsLoader.EventListener#onAdPlaybackState(androidx.media3.common.AdPlaybackState)` is or will be called, false otherwise. |

### handlePrepareComplete

```
@UnstableApi
fun handlePrepareComplete(
    adsMediaSource: AdsMediaSource!,
    adGroupIndex: Int,
    adIndexInAdGroup: Int
): Unit
```

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

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

### handlePrepareError

```
@UnstableApi
fun handlePrepareError(
    adsMediaSource: AdsMediaSource!,
    adGroupIndex: Int,
    adIndexInAdGroup: Int,
    exception: IOException!
): Unit
```

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/kotlin/androidx/media3/exoplayer/source/ads/AdsMediaSource`.

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

### release

```
fun release(): Unit
```

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

### setPlayer

```
fun setPlayer(player: Player?): Unit
```

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 |
|---|---|
| `player: https://developer.android.com/reference/kotlin/androidx/media3/common/Player?` | The player instance that will play the loaded ads. May be null to delete the reference to a previously set player. |

### setSupportedContentTypes

```
@UnstableApi
fun setSupportedContentTypes(@C.ContentType contentTypes: IntArray<Int>!): Unit
```

Sets the supported content types for ad media. Must be called before the first call to `https://developer.android.com/reference/kotlin/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/kotlin/androidx/media3/exoplayer/source/ads/AdsMediaSource`.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/kotlin/androidx/media3/common/C.ContentType contentTypes: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int-array/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html>!` | The supported content types for ad media. Each element must be one of `https://developer.android.com/reference/kotlin/androidx/media3/common/C#CONTENT_TYPE_DASH()`, `https://developer.android.com/reference/kotlin/androidx/media3/common/C#CONTENT_TYPE_HLS()`, `https://developer.android.com/reference/kotlin/androidx/media3/common/C#CONTENT_TYPE_SS()` and `https://developer.android.com/reference/kotlin/androidx/media3/common/C#CONTENT_TYPE_OTHER()`. |

### start

```
@UnstableApi
fun start(
    adsMediaSource: AdsMediaSource!,
    adTagDataSpec: DataSpec!,
    adsId: Any!,
    adViewProvider: AdViewProvider!,
    eventListener: AdsLoader.EventListener!
): Unit
```

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

Requests the ads loader to start loading ad data from the provided `https://developer.android.com/reference/kotlin/androidx/media3/datasource/DataSpec`. Publishing an initial `https://developer.android.com/reference/kotlin/androidx/media3/common/AdPlaybackState` to provided `https://developer.android.com/reference/kotlin/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 |
|---|---|
| `adsMediaSource: https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsMediaSource!` | The ads media source requesting to start loading ads. |
| `adTagDataSpec: https://developer.android.com/reference/kotlin/androidx/media3/datasource/DataSpec!` | A data spec for the ad tag to load. |
| `adsId: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html!` | An opaque identifier for the ad playback state across start/stop calls. |
| `adViewProvider: https://developer.android.com/reference/kotlin/androidx/media3/common/AdViewProvider!` | Provider of views for the ad UI. |
| `eventListener: https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/source/ads/AdsLoader.EventListener!` | Listener for ads loader events. |

### stop

```
@UnstableApi
fun stop(
    adsMediaSource: AdsMediaSource!,
    eventListener: AdsLoader.EventListener!
): Unit
```

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

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