Android

Embed Experiences using the Android SDK

This quick-start outlines how to integrate the Monterosa Interaction SDK in your Android app to enable real-time interactions. The SDK allows for easy implementation of interactive features such as live polls, quizzes, and more. Setting up requires both actions in your app and updates in the Monterosa Interaction Cloud platform.

---

Before you begin

You can request access to the Android SDK via [email protected] or your account manager. This will provide you with a username and token.

Step by step guide

1

Add Maven Configuration

In your project's settings.gradle.kts or settings.gradle file, add the Maven repository configuration to access the Android SDK.

Kotlin

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
    repositories {
        maven {
            url = uri("https://gitlab.com/api/v4/projects/38419902/packages/maven")
            credentials(HttpHeaderCredentials::class.java) {
                name = "Private-Token"
                // Replace with package token from the Welcome Pack
                value = "<package token>" 
            }
            authentication {
                val header by registering(HttpHeaderAuthentication::class)
            }
        }
    }
}

Groovy

2

Add the Embed SDK

To embed an experience, add the necessary dependencies to your module-level Gradle file (build.gradle.kts or build.gradle). Include the Identify dependency for SSO integration.

Kotlin

plugins {
    id("kotlin-parcelize")
}

dependencies {
    val sdkVersion = "0.16.16"
    
    // Add the Core dependency
    implementation("co.monterosa.sdk:core:$sdkVersion")
    
    // Add the dependency for embedding experiences
    implementation("co.monterosa.sdk:launcherkit:$sdkVersion")
    
    // Optional - Integration with SSO
    implementation("co.monterosa.sdk:identifykit:$sdkVersion")
}

Groovy

And finally, add the following rule to your proguard-rules.pro file :

# Monterosa SDK rules
-keep class co.monterosa.sdk.** { *; }
-dontwarn java.lang.management.**
-dontwarn androidx.window.extensions.**
-dontwarn androidx.window.extensions.embedding.**
-dontwarn androidx.window.sidecar.**

You may need to invalidate Anroid Studio's cache if this error is raised:

Gradle sync (Failed to resolve: co.monterosa.sdk:{kit}:X.Y.Z and Failed to resolve: co.monterosa.sdk:{kit}:X.Y.Z).

To invalidate the cache you'll need to delete the cache folder, which is located at:

On Windows: %USERPROFILE%.gradle\caches

On Mac/UNIX: ~/.gradle/caches/

You can browse to these directory and manually delete it or run on your terminal:

rm -r $HOME/.gradle/caches/

After that use the Invalidate Caches / Restart option of Android Studio.

3

Embed the Experience

After adding the required dependencies, you can begin embedding the experience into your app.

Compose

// Configure Core in your Application or Activity
Core.configure(context, "<host>", "<project id>")

// Add Experience as a composable
@Composable
fun Experience() {
    AndroidView(
        modifier = modifier.fillMaxSize(),
        factory = { context ->
            val config = ExperienceConfiguration()
            
            Launcher
                .default
                .getExperience(
                    context = context,
                    configuration = config
                )
        }
    )
}

Views

4

Listen to Experience State Changes

The ExperienceViewListener enables monitoring and handling of lifecycle state changes, messages, and errors in your Experience when necessary.

...
val experienceViewListener = object: ExperienceViewListener {
    // Override optional listeners here
}

Launcher.default.getExperience(
    context = context,
    configuration = config
).apply {
    // Attach the listener to your Experience
    listener = experienceViewListener
}
...

5

Get Logs from the Experience

Enable debugging logs from the Experience by activating logging in the Core package within your application class. Configure this setting based on the build type to prevent logs from appearing in the production app.

override fun onCreate() {
    super.onCreate()
    Core.enableLogging(true)
}

6

Clean Up the Experience

To ensure proper cleanup and resource management, it's recommended to clean up the Experience when destroying the app state. There are two ways to achieve this:

1. Attach the Experience to the activity's lifecycle during initialisation.

2. Explicitly call the destroy function from the Experience.

While both methods are effective, some scenarios require an explicit destroy call, especially when the lifecycle is linked to instances that outlive the Experience.

Compose

@Composable
fun Experience() {
    ...
    AndroidView(
        modifier = modifier.fillMaxSize(),
        factory = { context ->
            val config = ExperienceConfiguration()
            
            Launcher
                .default
                .getExperience(
                    context = context,
                    configuration = config
                )
        },
        onRelease = { experienceView -> 
            experienceView.destroy()
        }
    )
}

Views

Next Steps

Next, you will learn how to configure your experience to suit your requirements, extend certain behaviours, and communicate effectively with your experience.