Skip to main content

Panel Integration

Overview​

This guide walks you through integrating panels into your Maestro Android SDK implementation. Panels provide interactive modules that exist outside the main video player interface, enabling rich user experiences.

Integration Steps​

1. Initialize the SDK​

Configure the MaestroManager singleton to obtain the SDK instance. This should be done at app launch or when you're ready to display Maestro content:

val sdk = MaestroManager.configure(
    context = applicationContext,
    maestroEventDelegate = this,
    params = MaestroSDKParameters(
        siteId = "your-site-id",
        eventData = null, // Provide the initial event data, if any
    ),
)

2. Create the Event ViewModel and Render the Panel​

Initialize MaestroEventViewModel and display the MaestroPanel() composable. Make sure that the key corresponds to the SDK instance to ensure the ViewModel lifecycle corresponds to the SDK instance's lifecycle:

@Composable
fun maestroEventViewModel(sdk: MaestroSDKInstance) = viewModel(
    modelClass = MaestroEventViewModel::class.java,
    factory = MaestroEventViewModelFactory(sdk = sdk),
    key = "eventVM" + sdk.hashCode().toString(),
)

MaestroPanel(
    maestroEventViewModel = maestroEventViewModel(sdk),
    // Pass the desired padding here, as the panel will fill given size
    modifier = Modifier
        .fillMaxSize()
        .padding(horizontal = 24.dp)
        .padding(top = 30.dp),
)

3. Handle Panel Events​

Implement the MaestroEventDelegate methods to handle panel visibility and interactions:

class MyActivity : ComponentActivity(), MaestroEventDelegate {

    // Called when the SDK wants to show the panel
    override fun shouldShowPanel() {
        // Update your UI state to display the panel
    }

    // Called when the SDK wants to hide the panel
    override fun shouldHidePanel() {
        // Update your UI state to hide the panel
    }

    // Called when a specific panel is selected
    override fun onPanelSelected(panel: MaestroPanelType) {
        // Handle panel selection (e.g., analytics, UI updates)
    }

    // Other delegate methods...
}

4. Notify the SDK of Panel Visibility Changes​

When your app shows or hides the panel, notify the SDK using the MaestroEventInterface:

val viewModel = maestroEventViewModel(sdk)

// When showing the panel
viewModel.didShowPanel(MaestroPanelType.Chat)

// When hiding the panel
viewModel.didHidePanel()

Complete Example​

Here's a complete example integrating panels into a Composable screen:

@Composable
fun MaestroScreen(sdk: MaestroSDKInstance) {
    val viewModel = maestroEventViewModel(sdk)
    var isPanelVisible by remember { mutableStateOf(false) }

    Box(modifier = Modifier.fillMaxSize()) {
        // Your video player or main content
        VideoPlayer(
            modifier = Modifier.fillMaxSize()
        )

        // Maestro Panel
        if (isPanelVisible) {
            MaestroPanel(
                maestroEventViewModel = viewModel,
                modifier = Modifier
                    .fillMaxSize()
                    .padding(horizontal = 24.dp)
                    .padding(top = 30.dp),
            )

            // Notify SDK that panel is visible
            LaunchedEffect(Unit) {
                viewModel.didShowPanel(MaestroPanelType.Chat)
            }
        }
    }
}

Best Practices​

  • Proper Lifecycle Management: Ensure the ViewModel is scoped correctly to the SDK instance
  • Clean Up Resources: Call sdk.detach() when you're done with the SDK to stop all work
  • Handle Configuration Changes: Use proper state management to handle device rotation and other configuration changes
  • Responsive Layouts: Use appropriate modifiers to ensure panels look good on different screen sizes
  • Panel Visibility Notifications: Always notify the SDK when panel visibility changes using didShowPanel() and didHidePanel()
Last updated on