SDKs
Help centerCommunityDevelopersAcademyStatus

Integrate the Connect SDK into a native Android app (Jetpack Compose)

The Connect SDK captures behavioral data and enables mobile push notifications in native Android apps. This guide covers integrating the SDK into an app built with Jetpack Compose.

Language: Kotlin

Availability: Pro, Premium, and Ultimate

Requirements

  • Acoustic Connect subscription. You must register your app in Connect and get credentials for it. For instructions, see Connect mobile apps in the user guide.
  • Development environment. Android Studio.
  • Mobile app compatibility. Android 8.0 (API level 26) to Android 16 (API level 36).

Limitations

We do not guarantee that the current version of the library is compatible with Android apps using a mixture of the Android View framework and Jetpack Compose.

Prerequisites

Before you start the integration, make sure the following conditions are met:

  • AndroidManifest.xml has the following required permissions:
<!-- Required permissions -->
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>

<!-- Recommended permissions: location -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
  • Your Jetpack Compose project has the NavController class. The same navigation controller instance must be used throughout the navigation hierarchy.

Initial setup

  1. In gradle/libs.versions.toml, add the Connect SDK version and library entry.
[versions]
connect = "11.0.11"

[libraries]
connect = { module = "io.github.go-acoustic:connect", version.ref = "connect" }
  1. In the app-level build.gradle.kts, update the dependencies block to include the Connect SDK.
dependencies {
    implementation(libs.connect)
}

  1. Synchronize the project.

  2. Open the main entry point of the app and add an import statement for ConnectWrapper.

import com.acoustic.connect.android.connectmod.composeui.ConnectComposeUI.Companion.ConnectWrapper
  1. Customize the ConnectWrapper function for your app. Replace the placeholders with your Connect credentials.
ConnectWrapper(
    navController = navController,
    appKey = "YOUR_APP_KEY",
    postMessageURL = "YOUR_COLLECTOR_URL"
) { ... }

  1. Integrate ConnectWrapper at the root level of your app's composition.

  2. Build and run your app to verify the integration.

ConnectWrapper parameters

ParameterDescription
navControllerThe navigation controller instance. Valid values: navController and appState.navController.
appKeyThe application key generated for the current app in Connect.
postMessageURLThe collector endpoint associated with your Connect subscription.

ConnectWrapper integration examples

There are different ways to integrate ConnectWrapper with your navigation setup. Choose the approach that best fits the app architecture.

If your app uses a direct navigation controller, add ConnectWrapper right after you call rememberNavController():

@Composable
fun YourApp() {
    val navController = rememberNavController()

    ConnectWrapper(
        navController = navController,
        appKey = "YOUR_APP_KEY",
        postMessageURL = "YOUR_COLLECTOR_URL"
    ) {
        YourNavHost(navController = navController)
    }
}

For better state management and testing, hoist navController to a state holder:

class YourAppState(val navController: NavHostController) {
    // Other state management...
}

@Composable
fun rememberYourAppState(navController: NavHostController = rememberNavController()): YourAppState {
    return remember(navController) { YourAppState(navController) }
}

@Composable
fun YourApp() {
    val appState = rememberYourAppState()

    ConnectWrapper(
        navController = appState.navController,
        appKey = "YOUR_APP_KEY",
        postMessageURL = "YOUR_COLLECTOR_URL"
    ) {
        // Your app content using appState
    }
}

If your app has multiple navigation graphs:

@Composable
fun YourApp() {
    val navController = rememberNavController()

    ConnectWrapper(
        navController = navController,
        appKey = "YOUR_APP_KEY",
        postMessageURL = "YOUR_COLLECTOR_URL"
    ) {
        NavHost(navController = navController, startDestination = "main") {
            // Your navigation graph
        }
    }
}

For apps with multiple back stack support:

@Composable
fun YourApp() {
    val navController = rememberNavController()
    val configuration =
        NavHostController.Configuration(
            navigatorProvider = navController.navigatorProvider,
            backStackBehavior = BackStackBehavior.MULTIPLE_BACK_STACKS
        )

    ConnectWrapper(
        navController = navController,
        appKey = "YOUR_APP_KEY",
        postMessageURL = "YOUR_COLLECTOR_URL"
    ) {
        // Your multi-stack navigation
    }
}
📘

Need a refresher?

See Define routes and create a NavHostController in the Android documentation.

Next steps

Updated about 5 hours ago