Skip to content

AdManager

Jump to bottom
Anirudh Ramanan edited this page Jan 22, 2020 · 1 revision

This is the core piece of the library. The AdManager is responsible for deciding which ad break to play (depending upon the current progress of the content), firing events (both for content as well as the ad events such as STARTED, PROGRESS, FIRST_QUARTILE etc), and starting and ending the ad playback.

API's:

  • initialise(contentProgressProvider: ContentProgressProvider) - This is where the ad manager starts the handler for fetching the progress of the content.

  • start() - Starting of the ad manager, does nothing as of now.

  • pause() - This is called when the user pauses the ad. It fires the pause event (if ad is being played) and removes the ad message handler.

  • resume() - This is called when the ad is resumed. It fires the resume event (if ad is in paused state) and attaches the ad message handler back for listening to ad events.

  • destroy() - When the ad manager is destroyed. It removes all the message handlers attached.

  • getCuePoints(): List - It returns all the cue points of all the ad break. The plugin calls this method and passes the values to the player for rendering the cue points on the timelines.

Flow:

  • As soon as onAdManagerLoaded is triggered, AdManager is initialised. AdRenderer, AdEventListener, AdErrorListener, AdLoader and the VMAP data are passed as constructor params to the ad manager.

  • The AdManager implements the AdPlayerCallback interface which is exposed by the AdRenderer. This provides callback back to the manager when the player starts / stops / pauses the ad.

  • The plugin calls the initialise method by passing the ContentProgressProvider as a parameter. The AdProgressProvider is already implemented by the Player interface which is exposed by the AdRenderer. These providers are used by the AdManager to fetch the current progress of both the content and the ad. As soon as AdManager is initialised, AdPlaybackState is created.

  • AdPlaybackState maintains the state of the ad playback such as if the ad is currently being played, etc. AdBreakFinder houses the logic of which ad break to be played based on the current position of the content.

  • The AdManager starts the ContentProgressHandler to fetch the progress of the media. Till the player is not ready, -1 is returned as the progress. Once we have a valid progress and duration of the media, the AdManager updates the AdPlaybackState with the duration of the media. (The AdPlaybackState uses the duration to replace the cue point time of all the post roll ads, which by default is -1)

  • It then checks if there are any pre-roll ads to be played, if not CONTENT_RESUME event is fired.

  • On every onMediaProgressUpdate call (which is called by handler every 1 second), AdPlaybackState's getPlayableAdBreak is called to fetch the ad break to play. Once we have an ad break to be played, we check for state of the ad break for further processing.

  • AdBreak has various states which are self explanatory: NOT_PLAYED, LOADING, LOADED, PLAYING, PLAYED

    Initially the state is NOT_PLAYED. The getPlayableAdBreak method of the AdPlaybackState's returns only those ad breaks whose states are NOT_PLAYED. If the state is NOT_PLAYED, and the current time is within the prefetch range defined (which is by default 4 seconds), the AdManager calls the VastAdProvider to fetch the vast response for the given ad break and updates the state of ad break as LOADING. Once the vast ad is received and an ad exists, the ad load event is triggered along with the AdElement and state of ad break changes to LOADED.

The AdElement is used by the plugin to get the pod index and various other parameters.

If the state is LOADED, and the current time is greater than equal to the cue point of the loaded ad break, fire the play event and update the state of the ad break to playing. This is when it starts the AdProgressHandler to fetch the progress of the ad. The events which are triggered here are described above.

Once the ad finishes, ie the state is PLAYED, the played event is triggered notifying the plugin that the ad has stopped and completed.

Note: If the VastAdProvider does not provide a vast ad to play, error event is fired.

  • The AdManager also implements the RendererViewCallback of the AdRenderer which is used to notify the manager about the clicks on the UI such as skip ad, learn more and more. On clicks, the corresponding events are triggered (SKIPPED etc)

  • As soon as the ad play event gets triggered, the ad manager starts the AdProgressHandler which is used to fetch the progress of the ad every 250 ms.

    • If the previous percentage is less than 0.25F and current percentage is greater than 0.25F, fire the FIRST_QUARTILE event.
    • If the previous percentage is less than 0.50F and current percentage is greater than 0.50F, fire the MIDPOINT event.
    • If the previous percentage is less than 0.75F and current percentage is greater than 0.75F, fire the THIRD_QUARTILE event.
    • If the previous percentage is less than 0F and current percentage is greater than 0F, fire the STARTED event.
    • For all other cases, fire the progress event.

  • When the ad is paused, the pause of the AdManager is called which removes the attached ad progress handler and fires the PAUSE event.

  • When the ad is resumed, the resume of the AdManager is called which attaches the ad progress handler and fires the RESUME event.

  • When all the ads have been played or on the finish of the post roll ad break, ALL_AD_COMPLETED event is fired.

Let's discuss this in detail:

AdBreakFinder:

AdBreakFinder is responsible for selecting an ad break to play based on the current position of the player.

  • findPlayableAdBreak(currentPosition: Float, contentStartPosition: Float, contentDuration: Float, adBreakList: List): AdBreak? - It expects the current content position, the content start position, the content duration and the list of all the available ad breaks and returns the ad break to be played.

The default ad break finder works on the below algorithm:

  1. Using two pointers for the previous cue point index (which denotes the previous cue point) and the next cue point index (which denotes the next cue point). Initially the previous cue point index and next cue point index to 0.

  2. Using both the index, get the previousCuePoint and the nextCuePoint. If the current position of the player is greater than the previous cue point and less than the next cue point (which means the position is b/w these two pointers), check the ad break at previous cue point (if any) is played or not.

  3. Ad break to be played will be the ad break at the next cue point if not already played. If the previous cue point is not played, give priority to the previous ad break before playing the ad break at next cue point.

  4. Now, to identify if the scrubber position has been moved by the user.

  • If the current position of the player is less than the previous and next cue index, which means the scrubber was moved behind
  • If the current position of the player is more than the previous and next cue index, which means the scrubber was moved ahead.
  • In both the cases, using linear search find out the previous and next cue point index of the ad breaks.

ContentProgressProvider:

The ContentProgressProvider provides the current progress of the content. The provider is implemented by the client and the library is responsible for calling the progress provider every x seconds to track the progress of the content. The client is expected to get the actual progress of the content from the player eg exo-player.

The current implementation calls the progress provider every 1 second and is used to decide which ad break should be played depending on the content progress.

AdProgressProvider:

The AdProgressProvider provides the current progress of the ad. The provider is implemented by the client and the library is responsible for calling the progress provider every x seconds to track the progress of the ad. The client is expected to get the actual progress of the ad from the player eg exo-player.

The current implementation calls the progress provider every 100 ms, and all the event and tracking related events are sent depending on the current progress.

Vast Ad Providers:

It provides VAST ad to play for the given ad break

There are two variants of vast ad providers:

  • StringVastAdProvider: It reads the string vast data which is already in the VMAP response.
  • NetworkVastAdProvider: It interacts with the ad loader to fetch the vast from the given ad url.

Clone this wiki locally