Package com.castlabs.android.adverts

# Interface AdLoader

All Known Implementing Classes:
  `HlsInterstitialAdLoader`, `ServerAdLoader`

public interface AdLoader
The interface to provide SDK with the `Ad` properties The implementations are used by `ClientAdProvider.createAdLoader(AdRequest)`

Since:
  4.2.0

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static interface`
  `AdLoader.Listener`
  Listener for `AdLoader` events.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `createMediaSource(PlayerConfig playerConfig, PlayerPlugin playerPlugin, AdLoader.Listener listener)`
  Asynchronously create `MediaSource` to play
  `AdApi`
  `getAdApi()`
  Get an `AdApi` to issue custom operations to the ad provider
  `ViewGroup`
  `getAdContainer()`
  Returns ad UI container
  `long`
  `getAdPositionMs(Ad ad, com.google.android.exoplayer2.ExoPlayer player)`
  Returns the position of the provided `Ad` in milliseconds relative to the window that is currently playing (i.e.
  `Ad`
  `getCurrentAd()`
  Get the currently loaded and prepared for playing Ad
  `default com.google.android.exoplayer2.source.MediaSource`
  `maybeWrapMediaSource(com.google.android.exoplayer2.source.MediaSource mediaSource, PlayerConfig playerConfig)`
  Optionally wraps the given `MediaSource` with another `MediaSource`.
  `default void`
  `onContentMediaSource(PlayerConfig playerConfig, com.google.android.exoplayer2.source.MediaSource mediaSource)`
  Notifies the loader of the content `MediaSource` that will be used for playback.
  `void`
  `onPlayerStateChanged(boolean playWhenReady, int playbackState)`
  Called when the player state is changed
  `void`
  `onPositionDiscontinuity(int reason)`
  Called when the playback discontinuity occurs
  `long`
  `onSetPosition(long newPositionUs)`
  Called just before the `PlayerController` start seeking or setting a new position.
  `void`
  `release()`
  Release any unused resources
  `default boolean`
  `requiresMediaSourceHook()`
  Indicates whether this loader needs to create its own media source (client-side ads) or whether it operates on the content media source prepared by the player (server-side ads).
  `void`
  `scheduleAd(AdRequest adRequest)`
  Start loading an `AdRequest`.
  `void`
  `setPlayerController(PlayerController playerController)`
  Set the active `PlayerController` instance or `null` if there is no active `PlayerController` or it is about to be released

- ## Method Details

  - ### getCurrentAd

    @Nullable Ad getCurrentAd()
    Get the currently loaded and prepared for playing Ad
    Returns:
      The current Ad or `null`

  - ### getAdContainer

    @Nullable ViewGroup getAdContainer()
    Returns ad UI container
    Returns:
      ad UI container

  - ### setPlayerController

    void setPlayerController(@Nullable PlayerController playerController)
    Set the active `PlayerController` instance or `null` if there is no active `PlayerController` or it is about to be released
    Parameters:
      `playerController` - The `PlayerController` instance or `null`

  - ### release

    void release()
    Release any unused resources

  - ### requiresMediaSourceHook

    default boolean requiresMediaSourceHook()
    Indicates whether this loader needs to create its own media source (client-side ads) or whether it operates on the content media source prepared by the player (server-side ads).
    Returns:
      `true` if a media-source hook is required, `false` otherwise.

  - ### createMediaSource

    void createMediaSource(@NonNull PlayerConfig playerConfig, @NonNull PlayerPlugin playerPlugin, @NonNull AdLoader.Listener listener)
    Asynchronously create `MediaSource` to play
    Parameters:
      `playerConfig` - The `PlayerConfig`
      `playerPlugin` - The `PlayerPlugin`
      `listener` - The listener callback to provide the created `MediaSource`

  - ### onSetPosition

    long onSetPosition(long newPositionUs)
    Called just before the `PlayerController` start seeking or setting a new position. Can be used when the new position has to be adjusted by the `AdLoader` implementation e.g. to do ads snap back. If the adjustment is not needed then the provided position can simply be returned.
    Parameters:
      `newPositionUs` - The new position in microseconds
    Returns:
      The adjusted position in microseconds

  - ### onPlayerStateChanged

    void onPlayerStateChanged(boolean playWhenReady, int playbackState)
    Called when the player state is changed
    Parameters:
      `playWhenReady` - Play when ready flag
      `playbackState` - Playback state

  - ### onPositionDiscontinuity

    void onPositionDiscontinuity(@DiscontinuityReason int reason)
    Called when the playback discontinuity occurs
    Parameters:
      `reason` - The reason for discontinuity

  - ### scheduleAd

    void scheduleAd(@NonNull AdRequest adRequest)
    Start loading an `AdRequest`. This may be also called during playback. Support for on-request ad scheduling depends on the AdLoader implementation.
    Parameters:
      `adRequest` - The ad request to perform.

  - ### getAdApi

    @Nullable AdApi getAdApi()
    Get an `AdApi` to issue custom operations to the ad provider
    Returns:
      the `AdApi`

  - ### maybeWrapMediaSource

    default com.google.android.exoplayer2.source.MediaSource maybeWrapMediaSource(com.google.android.exoplayer2.source.MediaSource mediaSource, PlayerConfig playerConfig)
    Optionally wraps the given `MediaSource` with another `MediaSource`. This can be used to add custom behavior to the `MediaSource` before it is used by the player. By default, this method returns the original `MediaSource`.
    Parameters:
      `mediaSource` - The original `MediaSource`.
      `playerConfig` - The `PlayerConfig` to be used by the player.
    Returns:
      The wrapped `MediaSource`, or the original `MediaSource` if no wrapping is needed.

  - ### getAdPositionMs

    long getAdPositionMs(@NonNull Ad ad, @NonNull com.google.android.exoplayer2.ExoPlayer player)
    Returns the position of the provided `Ad` in milliseconds relative to the window that is currently playing (i.e. the media period exposed by `Player.getCurrentWindowIndex()`). Implementations that operate on concatenated timelines must therefore normalize the ad offset to the active window instead of returning a global playlist position.
    Parameters:
      `ad` - The ad for which the position should be resolved.
      `player` - The player instance that provides the current window context.
    Returns:
      The ad start position in milliseconds, relative to the currently playing window.

  - ### onContentMediaSource

    default void onContentMediaSource(@NonNull PlayerConfig playerConfig, @NonNull com.google.android.exoplayer2.source.MediaSource mediaSource)
    Notifies the loader of the content `MediaSource` that will be used for playback. This is invoked only for loaders that do not require a media-source hook.
    Parameters:
      `playerConfig` - The `PlayerConfig` associated with the media source.
      `mediaSource` - The content media source that will be prepared.