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

Scope: This guide covers integrating the Connect SDK for development and testing. For production configuration, see Prepare the Connect library for production use on Android devices.

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.

ConnectWrapper requires a NavHostController from Navigation-Compose (androidx.navigation.compose). Apps that have migrated to Navigation3 (androidx.navigation3) do not use NavHostController and are not compatible with the current SDK.

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"/>

<!-- Optional: add only if your app uses location tracking -->
<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 to the [versions] block.
[versions]
connect = "11.0.11"
  1. In the same file, add the Connect SDK library entry to the [libraries] block.
[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. Add ConnectWrapper to your root composable — the one called from setContent {} in your Activity. It must go after rememberNavController() and wrap everything that uses the NavController. Replace the placeholders with your Connect credentials.
@Composable
fun YourApp() {
    val navController = rememberNavController()

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

This inline pattern gets you running quickly during integration. Before you ship, move your credentials out of the source and split them by build type using BuildConfig fields — see Prepare for production.

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

ConnectWrapper parameters

ParameterDescription
navControllerThe NavHostController created with rememberNavController() in your root composable. Must be the same instance passed to your NavHost.
appKeyThe application key generated for the current app in Connect. If omitted or empty, the SDK falls back to a bundled default key — session data will not appear in your Connect account.
postMessageURLThe collector endpoint associated with your Connect subscription. If omitted or empty, the SDK falls back to a bundled default endpoint — always set this explicitly to ensure data reaches the correct Connect account.

ConnectWrapper integration examples

In most Compose apps, navController is created with rememberNavController() and passed directly to the NavHost. Add ConnectWrapper immediately after that call:

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

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

If your app hoists navController into a state holder for better state management and testing, pass it from there. Because both ConnectWrapper and the rest of the app use the same appState.navController instance, no additional configuration is needed:

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
    }
}

Verify the SDK is running

The Connect Android library ships with verbose logging enabled by default. Once you complete the integration steps above, run your app and open Logcat in Android Studio. Use the following filter, replacing your.app.id with your app's application ID:

package:your.app.id | tag:Tealeaf | tag:EOCore | tag:Connect

Navigate between screens and interact with the app. You should see output similar to this:

I  EOCore  ConnectComposeUI -Compose UI is detected
I  EOCore  ConnectComposeUI -Navigation changed to: com.example.app.Route.Home
I  EOCore  ConnectComposeUI -Navigated to route: com.example.app.Route.Home
I  EOCore  Http status: 200 from url: https://lib-us-1.brilliantcollector.com/collector/collectorPost
I  EOCore  PostTask message sent to the target server successfully.

Compose UI is detected confirms the SDK initialized correctly. Navigation changed and Navigated to route confirm screen tracking is working. Http status: 200 and PostTask message sent confirm data is reaching your collector. The session ID in PostTask is stable for the duration of the app session — use it to locate the session in Connect.

Verbose logging is convenient during integration but should be disabled before you ship. For instructions, see Prepare for production.

Next steps

  • Identify users — send a logged in or account registered signal so Connect can match the app visitor to a known contact.
  • Behavior signals — send signals for add-to-cart, order, product view, search, and other interactions to drive contact activity and journeys in Connect.
  • Prepare for production — enable privacy protection, disable Logcat output, and configure the kill switch before releasing to end users.