VpaidState.java

Overview

`VpaidState.java` defines the **VpaidState** class, a concrete state within the media player's finite state machine (FSM) responsible for handling playback of **VPAID (Video Player Ad-Serving Interface Definition)** ads. VPAID ads are interactive advertisements played inside a WebView rather than a standard video player.

This state manages pausing all existing ExoPlayer instances (both content and ad players), initializing the VPAID client with the next ad, making the WebView visible to display the interactive VPAID ad, and hiding other UI components such as subtitles and the main video view. It also defines transitions from this state based on input events related to VPAID ad playback.

Detailed Class Explanation

Class: VpaidState

public class VpaidState extends BaseState

• Extends: BaseState

• Purpose: Represents the FSM state where an interactive VPAID ad is playing within a WebView. It pauses regular playback and shows the VPAID ad interface.

Key Methods

1. transformToState

@Override
public State transformToState(Input input, StateFactory factory)

• Purpose: Defines possible state transitions from VpaidState based on received Input events.

• Parameters:

  • Input input — The event/input triggering potential state change (e.g., VPAID ad finished, next ad available).

  • StateFactory factory — Factory instance to create new state objects.

• Returns:

  • The next State instance to transition to, or null if no transition matches.

• Behavior:

• Usage Example:

State nextState = vpaidState.transformToState(Input.VPAID_FINISH, stateFactory);
if (nextState != null) {
    fsmPlayer.setCurrentState(nextState);
}

2. performWorkAndUpdatePlayerUI

@Override
public void performWorkAndUpdatePlayerUI(@NonNull FsmPlayer fsmPlayer)

• Purpose: Carries out the work needed in the VpaidState, including pausing players, initializing the VPAID client, and updating the UI to show the VPAID WebView.

• Parameters:

  • FsmPlayer fsmPlayer — The finite state machine player managing playback and state transitions.

• Behavior:

  • Calls the superclass implementation first.

  • Checks if fsmPlayer is null, returning early if so.

  • Invokes pausePlayerAndSHowVpaid helper method to perform the core operations of this state.

• Usage: Called by the FSM when entering or during the VpaidState to ensure correct UI and playback behavior.

3. pausePlayerAndSHowVpaid

private void pausePlayerAndSHowVpaid(
    PlayerUIController controller,
    PlayerAdLogicController componentController,
    FsmPlayer fsmPlayer,
    AdMediaModel adMedia)

• Purpose: Core logic to pause all ExoPlayer instances, initialize the VPAID client with the next ad, and update UI to display the VPAID WebView.

• Parameters:

  • PlayerUIController controller — Controls UI components including players and ad views.

  • PlayerAdLogicController componentController — Manages ad logic and holds the VpaidClient.

  • FsmPlayer fsmPlayer — FSM player instance controlling playback state.

  • AdMediaModel adMedia — Model managing the queue of ads to be played.

• Behavior:

  1. Gets the content player (moviePlayer) and pauses it if currently playing.

  2. Gets the ad player (adPlayer) and pauses it if currently playing.

  3. Retrieves the VpaidClient from the ad logic controller.

  4. Obtains the next ad (MediaModel) from adMedia.nextAD().

     • If no ad is available, logs a warning and returns.

  5. Initializes the VpaidClient with the next ad.

  6. Hides the main ExoPlayer view (controller.getExoPlayerView()).

  7. Shows the VPAID WebView (controller.getVpaidWebView()), brings it to front, and invalidates it to refresh.

  8. Adds the VpaidClient as a JavaScript interface to the WebView with the name "TubiNativeJSInterface".

  9. Loads the VPAID endpoint URL from the FSM player into the WebView.

  10. Hides the subtitle view on the ExoPlayer to avoid UI overlap.

• Important Notes:

  • This method ensures that the interactive VPAID ad takes over the screen and playback control.

  • The VpaidClient handles communication with the JavaScript VPAID ad inside the WebView.

• Example Usage: This method is invoked internally during performWorkAndUpdatePlayerUI.

Implementation Details and Algorithms

• State Pattern:
  VpaidState follows the FSM design by encapsulating behavior and transitions specific to VPAID ad playback.

• Player Pausing:
  Both the main content player and the standard ad player (ExoPlayer instances) are paused to prevent audio/video overlap.

• VPAID Ad Initialization:
  The VPAID client is initialized with the next ad, which triggers loading of the VPAID ad content into the WebView.

• UI Manipulation:
  The method makes the main video player invisible and shows the WebView, ensuring the interactive ad is prominently displayed.

• JavaScript Bridge:
  The VPAID client is exposed to the WebView's JavaScript environment via addJavascriptInterface, enabling communication from the ad scripts back to the native code.

• Logging:
  Uses ExoPlayerLogger.w for warnings when expected ads or clients are missing.

Interaction with Other System Parts

• Finite State Machine (FsmPlayer):
  The VpaidState is one of several states used by the FSM to handle playback scenarios. Transitions into and out of this state occur based on FSM inputs.

• Player Controllers:

  • PlayerUIController manages UI elements like the ExoPlayer views and the VPAID WebView.

  • PlayerAdLogicController manages ad-related logic and holds the VpaidClient instance.

• VpaidClient:
  An interface implemented by classes (e.g., TubiVPAID) that handle initialization and communication with VPAID ads running inside a WebView.

• Ad Media Model (AdMediaModel):
  Provides the next ad to be played, ensuring the VPAID client is initialized with the correct ad content.

• JavaScript Interface:
  The WebView hosting the VPAID ad interacts with native code through the JavaScript interface registered here.

Usage Example

// Assuming FSM player is currently in VpaidState
VpaidState vpaidState = new VpaidState();
StateFactory factory = new StateFactory();

// Transition example based on input
State nextState = vpaidState.transformToState(Input.VPAID_FINISH, factory);
if (nextState != null) {
    fsmPlayer.setCurrentState(nextState);
    nextState.performWorkAndUpdatePlayerUI(fsmPlayer);
}

// Within the FSM loop, performWorkAndUpdatePlayerUI is called automatically
vpaidState.performWorkAndUpdatePlayerUI(fsmPlayer);

Mermaid Class Diagram

classDiagram
    class VpaidState {
        +transformToState(input: Input, factory: StateFactory): State
        +performWorkAndUpdatePlayerUI(fsmPlayer: FsmPlayer): void
    }
    VpaidState --|> BaseState
    BaseState <|-- VpaidState

• Explanation:

  • VpaidState extends BaseState.

  • Public methods shown include the main FSM transition method and the UI/work update method.

  • Private helper method pausePlayerAndSHowVpaid is omitted for clarity.

Summary

`VpaidState.java` is a concise but crucial part of the media playback FSM responsible for integrating VPAID interactive ads into the native playback experience via a WebView. It handles pausing other video players, initializing the VPAID client with the correct ad, managing UI visibility, and processing state transitions triggered by VPAID ad lifecycle events. This design allows the media player to seamlessly switch between standard video ads, interactive VPAID ads, and main content playback while maintaining a clean and modular finite state machine architecture.