Skip to main content

Installation and Integration

This guide will walk you through installing the Maestro Android SDK and integrating it into your Android application.

Prerequisites​

Before you begin, make sure you have:

  • Android Studio installed
  • Kotlin support enabled in your project
  • Jetpack Compose set up
  • Your Maestro siteID. For directions to obtain your siteId, see our Maestro SDK Getting Started Guide here.
  • A GitHub Personal Access Token (PAT) for accessing the SDK package

Installation​

1. Add the SDK Dependency​

Define the dependency in your build.gradle (app/module level):

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

2. Configure Maven Repository​

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. MaestroManager: A singleton used for SDK initialization and configuration.
  2. MaestroSDKInstance: Represents a single initialized Maestro SDK session. Returned by the configure call from the MaestroManager.
  3. MaestroEventDelegate: A delegate interface implemented by the client app to let the SDK notify the app of relevant events.
  4. MaestroEventInterface: The API used to let the client app notify the SDK of certain events and control UI functionalities. Implemented by MaestroEventViewModel.

Basic Integration Steps​

1. Import and Configure the SDK​

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

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

2. Initialize the ViewModel​

To display MaestroPanel(), first initialize MaestroEventViewModel.

You can use the maestroEventViewModel composable function or manually instantiate it, but make sure that the key corresponds to the SDK instance (to ensure the lifecycle of the ViewModel 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(),
)

3. Display the Panel​

Render the MaestroPanel composable:

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),
)
Last updated on