Maestro Panel SDK for Jetpack Compose Documentation

Overview

This SDK simplifies integrating interactive panels into your Jetpack Compose Android applications. It provides APIs for event handling, user interaction, and UI updates, enabling rich user experiences. The core composable is MaestroPanel(), which displays the panel. MaestroManager is a singleton object used for SDK initialization and management.

Installation

implementation("com.lessthan3:maestropanel:2.0.5")

In settings.gradle, add the maven repository:

maven {
    name = "GitHubPackages"
    url = uri("https://maven.pkg.github.com/lessthan3/MaestroKit.android")
    credentials {
       username = "your_git_username"
       password = "your_git_personal_access_token"
    }
}

Use your own Github username and generate your own PAT. Note: the PAT must have a validity of at most 1 year.

Key Concepts and Interfaces

The SDK uses these key interfaces:

1. MaestroManagerInterface: For SDK initialization, configuration, and event lifecycle management. Interacted with through the MaestroManager singleton object.
2. MaestroEventInterface: API for your app to interact with the SDK concerning the currently loaded event (e.g., clip playback, progress tracking). Implemented by MaestroEventViewModel.
3. MaestroEventDelegate: Your app implements this to provide event-specific data and handle playback requests from the SDK.
4. MaestroSDKInstance: Represents the instance of the SDK session with which you can interact. Returned by the configure call from the MaestroManager.

Usage

1. Initialize the SDK

At app launch, configure the MaestroManager singleton to obtain the SDK instance:

val sdk = MaestroManager.configure(
    siteId = "yourSiteId",
    workingEnvironment = WorkingEnvironment.TESTING,
    maestroEventDelegate = this, // your delegate
    scope = MaestroSDKScope.Create(applicationContext),
)

2. Displaying the Panel and Initializing the ViewModel

To display MaestroPanel(), first initialize MaestroEventViewModel:

val maestroEventViewModel = viewModel(
    modelClass = MaestroEventViewModel::class.java,
    factory = MaestroEventViewModelFactory(sdk = sdk),
)

MaestroPanel(
    maestroEventViewModel = maestroEventViewModel
)

// use maestroEventViewModel and the sdk instance to interact with the SDK (e.g., playClip, track progress)

API Reference

MaestroManagerInterface

interface MaestroManagerInterface {
    /** This configures the SDK and must be called at app launch.*/
    fun configure(siteId: String,
                  workingEnvironment: WorkingEnvironment,
                  maestroEventDelegate: MaestroEventDelegate,
                  scope: MaestroSDKScope
    ): MaestroSDKInstance
    
    /**
     * Tells the SDK that the user has opened an event in the app's player.
     *
     *  you can just create a viewmodel and pass to the maestro panel
     *  use [MaestroEventViewModelFactory]
     * */
    fun userDidStartWatchingEvent(eventId: String?)

    /** Tells the SDK the user has closed an event that was open in the app's player.*/
    suspend fun userDidStopWatchingEvent(eventId: String)
}

MaestroManagerInterface

interface MaestroSDKInstance {

    /** Tells the SDK that the keyplay with index [index] needs to gain focus */
    fun onKeyPlayFocusChanged(index: Int)

    /**
     * Communicate to the SDK that the pinch back mode was entered (i.e. the client app went full-screen)
     */
    fun onPinchBackEntered()

    /**
     * Communicate to the SDK that the pinch back mode was exited (i.e. the client app exited full-screen and the Maestro panels are visible)
     */
    fun onPinchBackExited()

    /**
     * Detach the SDK and stop all the work it may be doing. Use this to control the lifecycle of the SDK, when needed.
     * The SDK cannot be used after this method is invoked.
     */
    fun detach()
}

MaestroEventInterface

/** Your app defines a delegate that is compliant with this protocol and provides a reference as part of your
initialization of the SDK.*/
interface MaestroEventDelegate {
    /**
    Enables the SDK to retrieve key plays data from the client app. Assumes the client app will retain a copy of
    the response so that the SDK and the app can remain in sync with their understanding of the currently-cached key plays data.
     */
    fun keyPlaysData(): StateFlow<MaestroResource<MaestroKeyPlaysResponse>>

    /**
     * The SDK instructs the client app to make a new load of the key plays data
     */
    fun onKeyPlaysRefreshNeeded()

    /**
     * A flow of authentication data to be used by the SDK to load the bets data.
     */
    fun authData(): StateFlow<MaestroAuthData?>?

    /**
    Allows the SDK to request the client app play a particular key plays clip, given its array index in the key plays list.
    Note that the `MaestroKeyPlaysResponse` subdivides the key plays by section, so the `index` referenced here assumes the
    client app has access to a flattened list of the key plays, disregarding the sectional subdivisions.
     */
    fun playClip(index: Int,clipId:String?)

    /** Allows the SDK to notify the client app of user actions for analytics tracking. Details TBD.*/
    fun trackAction(analytics: Map<String, String>)


    /** Allows the SDK to tell the client app that the panel should be displayed.*/
    fun shouldShowPanel()

    /** Allows the SDK to tell the client app that the panel should be dismissed.*/
    fun shouldHidePanel()

    //  Allows the SDK to tell the client app that the given overlay should be displayed.
    fun shouldShowOverlay(event: MaestroOverlayEvent)

    //  Allows the SDK to tell the client app that the currently-displayed overlay should be dismissed.
    fun shouldHideOverlay()

    /** Allows the SDK to notify the client app of user impressions for analytics tracking. Details TBD.*/
    fun trackImpression(analytics: Map<String, String>)
}

MaestroEventDelegate

/**
 * This is the public API that the app can use to make calls to the SDK related to the currently-loaded event.
 */
interface MaestroEventInterface {

    /**
     * Tells the SDK that the user just started playing a new key play clip at the given index.
     */
    fun didStartPlayingClip(index: Int)

    /**
     * Tells the SDK that the user just stopped playing a key play clip at the given index.
     */
    fun didStopPlayingClip(index: Int)

    /** Tells the SDK that the user tried to play the clip but it failed to play back.*/
    fun clipDidFailToPlay(index : Int)

    /**
     * Updates the SDK with the latest progress in the playback of the currently-played key play clip, from 0 to 1.
     */
    fun didUpdatePlaybackProgressOfClip(index: Int, progress: Float)

    /**
     * Tells the SDK that the app displayed the MaestroPanel.
     */
    fun didShowPanel(maestroPanelType: MaestroPanelType)

    /**
     * Tells the SDK that the app hid the MaestroPanel.
     */
    fun didHidePanel()
    
    /// Tells the SDK that the app displayed the MaestroOverlay.
    fun didShowOverlay()

    /// Tells the SDK that the app displayed the MaestroOverlay.
    fun didHideOverlay()

    /**
     * Retrieves the event ID for the currently loaded event.
     */
    fun getCurrentEventID(): StateFlow<String?>

    /**
     * Retrieves the array index of the key play clip that is currently being played.
     */
    fun getCurrentlyPlayingClipIndex(): StateFlow<Int>

    /**
     * Retrieves the array index of the key plays clip that was most recently played.
     */
    fun getLastPlayedClipIndex(): StateFlow<Int?>

    /**
     * Retrieves the progress (between 0 and 1) of the currently-played key play clip.
     */
    fun getCurrentClipPlaybackProgress(): StateFlow<Float>

    /**
     * Retrieves the number of key plays.
     */
    fun getKeyPlaysCount(): StateFlow<Int>
}