Track and name Android screens

On this page

Give your screens names your product team recognizes, such as Product, Cart or Checkout: payment. Use Android screen labels to describe the visible destination or state without creating extra navigation events.

Applies to native Android SDK 1.2.0.

The SDK observes Activity and Fragment transitions automatically. For Jetpack Compose Navigation, register the navigation controller to observe destination changes.

A technical Activity or route name is not always a useful product name. Several screens can share an Activity, and a screen can have meaningful states such as delivery and payment. Add a label when that distinction helps your analysis.

import io.cux.analytics_sdk.composable.monitor

navController.monitor(actualHostView)

Use the View your app already renders into. If you have several navigation hosts, use the View belonging to this controller. Do not register a helper View or assume that the foreground Activity identifies the correct host.

The no-argument navController.monitor() remains available for destination tracking. Use the View-taking overload when you need screen labels. Registration alone does not mean the destination is already visible and ready to name.

Name the current screen

Call screen() on the main thread after the screen's host is attached, visible and focused:

import io.cux.analytics_sdk.CuxAnalytics

CuxAnalytics.screen("Checkout: payment")

Call it from the point where your app knows the correct destination is visible. An Activity's onCreate(), a Fragment's onViewCreated() or a composable entering composition can happen too early.

If the SDK cannot recognize an active screen, it ignores the call. It does not save the name for the next screen. When an early call is ignored, call again when the intended screen is actually ready; do not name a later destination on its behalf.

Choose stable names

Use Product, Cart or Checkout: payment. Keep names consistent between app versions and include a state only when it changes the meaning of the screen.

Do not put customer names, order IDs, emails or URL arguments in labels. Use a separate custom event for an outcome such as payment success.

Understand label lifetime

The name stays on the recognized current screen until you replace it with another screen() call. Layout changes and scrolling do not clear it. A new screen does not inherit the previous name.

When the SDK recognizes a return to an earlier screen, it restores that screen's label. A new visit or process start clears labels. Repeating the same name for the same state does not create additional entrances.

A label is not a manual navigation marker. Native Android 1.2.0 does not provide sendScreen() or Modifier.trackScreen().

Identify interactive elements

To distinguish taps on a Compose component, give it a stable tag:

import androidx.compose.foundation.clickable
import androidx.compose.foundation.layout.Box
import androidx.compose.material3.Text
import androidx.compose.ui.Modifier
import io.cux.analytics_sdk.composable.monitorElement

Box(
    modifier = Modifier
        .monitorElement("checkout_continue")
        .clickable { onContinue() }
) {
    Text("Continue")
}

This example belongs inside your composable; onContinue is your existing action. A tag identifies the element, not the screen. Do not put customer data or changing list positions in a tag. Repeated instances need careful interpretation: one shared tag does not identify a unique item.

Use Modifier.maskAndMonitorElement("account_balance") when the component needs both a tag and screenshot masking. Verify the mask separately.

Declare expandable content when needed

You can identify an existing expandable View with:

CuxAnalytics.monitorExpandedContent(expandableView)

expandableView is the real region in your layout. This declaration does not measure element impressions, prove that content was seen or establish an exposure rate.

Verify screen names

Navigate Product > Cart > Checkout, then change Checkout from delivery to payment. Check the names in CUX and return to an earlier screen to check restoration.

Repeat after background/foreground transitions. Confirm that labels do not carry onto a different destination and that your naming calls do not create extra navigation.

If a label is missing, check the physical host and call timing before changing the name. Continue with Android troubleshooting.