Install the Android SDK

Install the CUX Android SDK to collect navigation, interactions and available screenshots from your app. Start with one test journey, then add screen names or custom events where you need more context.

Version covered: 1.2.0. Requires Android 8.0 / API 26 or later.

Requirements

• An Android app with minSdk 26 or higher.
• Gradle and a Kotlin or Java application.
• A CUX mobile project and its token from Settings > Project.

If you already use CUX, start with Upgrade to Android SDK 1.2.0. This native SDK guide does not update the React Native or Flutter packages.

Install the SDK

Add the public repository to your Gradle repository configuration. In projects using centralized repositories, add it to dependencyResolutionManagement.repositories in settings.gradle:

maven {
    url "https://packagecloud.io/cux/public-compose-gradle/maven2"
}

Add the dependency in your app module's build.gradle:

dependencies {
    implementation 'io.cux:analytics-compose-sdk:1.2.0'
}

Keep the repository in the place your build already uses. Do not add an allprojects repository block if your project forbids module-level repositories.

Required permissions

Check the merged manifest for these permissions:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

The SDK AAR supplies them, but your app's merged manifest is the result that matters.

Initialize the SDK

Initialize once in your Application class. Replace the placeholder with your mobile project token:

import android.app.Application
import io.cux.analytics_sdk.CuxAnalytics
import io.cux.analytics_sdk.logger.CuxLogLevel

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        CuxAnalytics.init(
            context = this,
            token = "YOUR_MOBILE_PROJECT_TOKEN",
            logLevel = CuxLogLevel.Production,
            needConfirmToStart = true
        )
    }
}

Register your Application class in the manifest if your app does not already use it.

This example waits for your app's consent handling to call CuxAnalytics.resumeCollectingData(). Set needConfirmToStart to false only when collection should start immediately. Do not add another initializer to enable a feature later.

What gets tracked automatically

The SDK observes Activity/Fragment navigation and touch interactions such as taps and long presses. It also collects device and foreground/background information. Screenshot capture depends on your project configuration and privacy settings.

For Jetpack Compose navigation, register your NavHostController as described below. Native scroll analytics and deferred campaign attribution are not activated in 1.2.0.

Name screens with custom labels

Use CuxAnalytics.screen(name) to name the currently visible screen or state. Labels do not create a new navigation event or visit. Read Track and name Android screens for readiness, naming and Back behavior.

Automatic Compose navigation tracking

Register the actual View containing your navigation controller's UI:

import io.cux.analytics_sdk.composable.monitor

navController.monitor(actualHostView)

actualHostView is your existing host View, not a new helper View. The no-argument monitor() tracks destination changes but does not establish the physical host required for screen labels. Follow the screen guide for details.

Tell us who the user is

Identification is optional. Use a stable internal ID when you need it, and keep personal data out of attributes. Follow Identify users.

Track custom events

Send an event when your app confirms an outcome, such as a completed checkout. Use trackEvent() for string parameters or trackEventTyped() for supported typed values. See Android custom events.

Control data collection

Connect consent and withdrawal to the SDK's collection methods. See Control Android collection.

Hide sensitive content from screenshots

Configure masks before using customer data. Check sensitive content beyond ordinary input fields. Follow Android masking.

XML / View-based

Register masks on your actual Views before sensitive content can be captured. See View masking.

Jetpack Compose

Apply the masking modifier to the sensitive composable or region. See Compose masking.

Monitor Compose elements for tap analytics

Use stable element tags when you need to distinguish taps on specific Compose components. See Identify interactive elements. This does not measure impressions.

Advanced init options

Keep one initializer with the project token, production logging level and your consent choice. initOptions is not a place to invent screenshot or sampling controls. Check mobile configuration before changing collection settings.

Optional preview stitching

Stitching is off by default. It requires compatible CUX processing and only uses captured content. Read Configure Android preview stitching before enabling it.

WebView integration

Connect a registered Android WebView to a separate CUX web project with a compatible collector and configured project pair. Follow Connect Android WebView.

Upgrading to 1.2.0

Check API 26, update the dependency and replace obsolete screen APIs. Follow the upgrade checklist.

Verify your first recording

1. Run a short journey on a test device after your app allows collection.
2. Navigate between screens and perform a few taps.
3. Find the visit in CUX and compare its screens and interactions with your actions.
4. Inspect available screenshots, including sensitive fields and overlays.
5. Test consent withdrawal and return to the app.

Keep advanced features off during this initial check. If expected data is missing, use Troubleshoot your Android integration.