Package com.google.android.exoplayer2.ext.ima

## Class ImaAdsLoader

- java.lang.Object
- - com.google.android.exoplayer2.ext.ima.ImaAdsLoader

- All Implemented Interfaces:
    `AudioListener`, `DeviceListener`, `MetadataOutput`, `Player.EventListener`, `Player.Listener`, `AdsLoader`, `TextOutput`, `VideoListener`

      public final class ImaAdsLoader
      extends Object
      implements Player.Listener, AdsLoader

  `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 `setPlayer(Player)`. If the ads loader is no longer required, it must be released by calling `release()`.

  See 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 `DataSpec` when constructing the `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 `Util.getDataUriForString(String, 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 `AdViewProvider` passed to the `AdsMediaSource`. See the IMA SDK Open Measurement documentation for more information.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `ImaAdsLoader.Builder` | Builder for `ImaAdsLoader`.

    - ### Nested classes/interfaces inherited from interface com.google.android.exoplayer2.source.ads.AdsLoader

      `AdsLoader.EventListener`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `focusSkipButton()` | Moves UI focus to the skip button (or other interactive elements), if currently shown.
    `com.google.ads.interactivemedia.v3.api.AdDisplayContainer` | `getAdDisplayContainer()` | Returns the `AdDisplayContainer` used by this loader, or `null` if ads have not been requested yet.
    `com.google.ads.interactivemedia.v3.api.AdsLoader` | `getAdsLoader()` | Returns the underlying `AdsLoader` wrapped by this instance, or `null` if ads have not been requested yet.
    `void` | `handlePrepareComplete​(AdsMediaSource adsMediaSource, int adGroupIndex, int adIndexInAdGroup)` | Notifies the ads loader that preparation of an ad media period is complete.
    `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.
    `void` | `onPositionDiscontinuity​(Player.PositionInfo oldPosition, Player.PositionInfo newPosition, int reason)` | Called when a position discontinuity occurs.
    `void` | `onRepeatModeChanged​(int repeatMode)` | Called when the value of `Player.getRepeatMode()` changes.
    `void` | `onShuffleModeEnabledChanged​(boolean shuffleModeEnabled)` | Called when the value of `Player.getShuffleModeEnabled()` changes.
    `void` | `onTimelineChanged​(Timeline timeline, int reason)` | Called when the timeline has been refreshed.
    `void` | `release()` | Releases the loader.
    `void` | `requestAds​(DataSpec adTagDataSpec, Object adsId, ViewGroup adViewGroup)` | Requests ads, if they have not already been requested.
    `void` | `setPlayer​(Player player)` | Sets the player that will play the loaded ads.
    `void` | `setSupportedContentTypes​(int... contentTypes)` | Sets the supported content types for ad media.
    `void` | `skipAd()` | Skips the current ad.
    `void` | `start​(AdsMediaSource adsMediaSource, DataSpec adTagDataSpec, Object adsId, AdViewProvider adViewProvider, AdsLoader.EventListener eventListener)` | Starts using the ads loader for playback.
    `void` | `stop​(AdsMediaSource adsMediaSource, AdsLoader.EventListener eventListener)` | Stops using the ads loader for playback and deregisters the event listener.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface com.google.android.exoplayer2.audio.AudioListener

      `onAudioAttributesChanged, onAudioSessionIdChanged, onSkipSilenceEnabledChanged, onVolumeChanged`

    - ### Methods inherited from interface com.google.android.exoplayer2.device.DeviceListener

      `onDeviceInfoChanged, onDeviceVolumeChanged`

    - ### Methods inherited from interface com.google.android.exoplayer2.Player.EventListener

      `onAvailableCommandsChanged, onEvents, onIsLoadingChanged, onIsPlayingChanged, onLoadingChanged, onMediaItemTransition, onMediaMetadataChanged, onPlaybackParametersChanged, onPlaybackStateChanged, onPlaybackSuppressionReasonChanged, onPlayerError, onPlayerStateChanged, onPlayWhenReadyChanged, onPositionDiscontinuity, onSeekProcessed, onStaticMetadataChanged, onTimelineChanged, onTracksChanged`

    - ### Methods inherited from interface com.google.android.exoplayer2.Player.Listener

      `onCues, onMetadata`

    - ### Methods inherited from interface com.google.android.exoplayer2.video.VideoListener

      `onRenderedFirstFrame, onSurfaceSizeChanged, onVideoSizeChanged, onVideoSizeChanged`

- - ### Method Detail

    - #### getAdsLoader

          @Nullable
          public com.google.ads.interactivemedia.v3.api.AdsLoader getAdsLoader()

      Returns the underlying `AdsLoader` wrapped by this instance, or `null` if ads have not been requested yet.

    - #### getAdDisplayContainer

          @Nullable
          public com.google.ads.interactivemedia.v3.api.AdDisplayContainer getAdDisplayContainer()

      Returns the `AdDisplayContainer` used by this loader, or `null` if ads have not been requested yet.

      Note: any video controls overlays registered via `BaseDisplayContainer.registerFriendlyObstruction(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 `AdViewProvider` when creating the media source to benefit from automatic registration.

    - #### requestAds

          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:
        `adTagDataSpec` - The data specification of the ad tag to load. See class javadoc for information about compatible ad tag formats.
        `adsId` - A opaque identifier for the ad playback state across start/stop calls.
        `adViewGroup` - A `ViewGroup` on top of the player that will show any ad UI, or `null` if playing audio-only ads.

    - #### skipAd

          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 `AdViewProvider`.

    - #### focusSkipButton

          public void focusSkipButton()

      Moves UI focus to the skip button (or other interactive elements), if currently shown. See `BaseManager.focus()`.

    - #### setPlayer

          public void setPlayer​(@Nullable
                                Player player)

      Description copied from interface: `AdsLoader`
      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()`).

      Specified by:
        `setPlayer` in interface `AdsLoader`
      Parameters:
        `player` - The player instance that will play the loaded ads. May be null to delete the reference to a previously set player.

    - #### setSupportedContentTypes

          public void setSupportedContentTypes​(@ContentType
                                               int... contentTypes)

      Description copied from interface: `AdsLoader`
      Sets the supported content types for ad media. Must be called before the first call to `AdsLoader.start(AdsMediaSource, DataSpec, Object, AdViewProvider, EventListener)`. Subsequent calls may be ignored. Called on the main thread by `AdsMediaSource`.
      Specified by:
        `setSupportedContentTypes` in interface `AdsLoader`
      Parameters:
        `contentTypes` - The supported content types for ad media. Each element must be one of `C.TYPE_DASH`, `C.TYPE_HLS`, `C.TYPE_SS` and `C.TYPE_OTHER`.

    - #### start

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

      Description copied from interface: `AdsLoader`
      Starts using the ads loader for playback. Called on the main thread by `AdsMediaSource`.
      Specified by:
        `start` in interface `AdsLoader`
      Parameters:
        `adsMediaSource` - The ads media source requesting to start loading ads.
        `adTagDataSpec` - A data spec for the ad tag to load.
        `adsId` - An opaque identifier for the ad playback state across start/stop calls.
        `adViewProvider` - Provider of views for the ad UI.
        `eventListener` - Listener for ads loader events.

    - #### stop

          public void stop​(AdsMediaSource adsMediaSource,
                           AdsLoader.EventListener eventListener)

      Description copied from interface: `AdsLoader`
      Stops using the ads loader for playback and deregisters the event listener. Called on the main thread by `AdsMediaSource`.
      Specified by:
        `stop` in interface `AdsLoader`
      Parameters:
        `adsMediaSource` - The ads media source requesting to stop loading/playing ads.
        `eventListener` - The ads media source's listener for ads loader events.

    - #### release

          public void release()

      Description copied from interface: `AdsLoader`
      Releases the loader. Must be called by the application on the main thread when the instance is no longer needed.
      Specified by:
        `release` in interface `AdsLoader`

    - #### handlePrepareComplete

          public void handlePrepareComplete​(AdsMediaSource adsMediaSource,
                                            int adGroupIndex,
                                            int adIndexInAdGroup)

      Description copied from interface: `AdsLoader`
      Notifies the ads loader that preparation of an ad media period is complete. Called on the main thread by `AdsMediaSource`.
      Specified by:
        `handlePrepareComplete` in interface `AdsLoader`
      Parameters:
        `adsMediaSource` - The ads media source for which preparation of ad media completed.
        `adGroupIndex` - The index of the ad group.
        `adIndexInAdGroup` - The index of the ad in the ad group.

    - #### handlePrepareError

          public void handlePrepareError​(AdsMediaSource adsMediaSource,
                                         int adGroupIndex,
                                         int adIndexInAdGroup,
                                         IOException exception)

      Description copied from interface: `AdsLoader`
      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 `AdsMediaSource`.
      Specified by:
        `handlePrepareError` in interface `AdsLoader`
      Parameters:
        `adsMediaSource` - The ads media source for which preparation of ad media failed.
        `adGroupIndex` - The index of the ad group.
        `adIndexInAdGroup` - The index of the ad in the ad group.
        `exception` - The preparation error.

    - #### onTimelineChanged

          public void onTimelineChanged​(Timeline timeline,
                                        @TimelineChangeReason
                                        int reason)

      Description copied from interface: `Player.EventListener`
      Called when the timeline has been refreshed.

      Note that the current window or period index may change as a result of a timeline change. If playback can't continue smoothly because of this timeline change, a separate `Player.EventListener.onPositionDiscontinuity(PositionInfo, PositionInfo, int)` callback will be triggered.

      `Player.EventListener.onEvents(Player, Events)` will also be called to report this event along with other events that happen in the same `Looper` message queue iteration.

      Specified by:
        `onTimelineChanged` in interface `Player.EventListener`
      Parameters:
        `timeline` - The latest timeline. Never null, but may be empty.
        `reason` - The `Player.TimelineChangeReason` responsible for this timeline change.

    - #### onPositionDiscontinuity

          public void onPositionDiscontinuity​(Player.PositionInfo oldPosition,
                                              Player.PositionInfo newPosition,
                                              @DiscontinuityReason
                                              int reason)

      Description copied from interface: `Player.EventListener`
      Called when a position discontinuity occurs.

      A position discontinuity occurs when the playing period changes, the playback position jumps within the period currently being played, or when the playing period has been skipped or removed.

      `Player.EventListener.onEvents(Player, Events)` will also be called to report this event along with other events that happen in the same `Looper` message queue iteration.

      Specified by:
        `onPositionDiscontinuity` in interface `Player.EventListener`
      Parameters:
        `oldPosition` - The position before the discontinuity.
        `newPosition` - The position after the discontinuity.
        `reason` - The `Player.DiscontinuityReason` responsible for the discontinuity.

    - #### onShuffleModeEnabledChanged

          public void onShuffleModeEnabledChanged​(boolean shuffleModeEnabled)

      Description copied from interface: `Player.EventListener`
      Called when the value of `Player.getShuffleModeEnabled()` changes.

      `Player.EventListener.onEvents(Player, Events)` will also be called to report this event along with other events that happen in the same `Looper` message queue iteration.

      Specified by:
        `onShuffleModeEnabledChanged` in interface `Player.EventListener`
      Parameters:
        `shuffleModeEnabled` - Whether shuffling of windows is enabled.

    - #### onRepeatModeChanged

          public void onRepeatModeChanged​(@RepeatMode
                                          int repeatMode)

      Description copied from interface: `Player.EventListener`
      Called when the value of `Player.getRepeatMode()` changes.

      `Player.EventListener.onEvents(Player, Events)` will also be called to report this event along with other events that happen in the same `Looper` message queue iteration.

      Specified by:
        `onRepeatModeChanged` in interface `Player.EventListener`
      Parameters:
        `repeatMode` - The `Player.RepeatMode` used for playback.