Track screen views with the Matomo SDK for Android

Screen views are recorded when you track user navigation to a new screen or section of your app. In Android, screens are implemented using activities, fragments, or composable destinations, so tracking is added to the component representing the visible screen.

This guide explains how to track additional screens in your Android app to record user navigation in Matomo. The example uses a Jetpack Compose app, where screens are implemented as composable destinations.

Before you start

Before continuing, ensure tracking is already set up and working in your app. Read more on setting up tracking with the Matomo SDK for Android.

Track views in a composable

To track additional screens in a Jetpack Compose app, send a screen view when a composable representing a screen becomes visible.

Each screen should handle its own tracking to ensure accurate reporting in Matomo. In this example, the tracker is retrieved from the global instance defined in MatomoApp.kt.

1. Go to the kotlin/ (or java/) directory and open the file that defines your screen composable.
2. Add the required Matomo imports at the top of the file:
   import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalContext
import org.matomo.sdk.Tracker
import org.matomo.sdk.extra.TrackHelper
3. Retrieve the tracker instance inside your composable using the application context.
   val tracker: Tracker =
(LocalContext.current.applicationContext as MatomoApp).getTracker()
4. Use LaunchedEffect to send a screen view when the composable is first displayed.
5. Ensure the screen path (for example /home) and title (for example Home) are unique for each screen so they can be distinguished in Matomo reports.

@Composable
fun HomeScreen(modifier: Modifier = Modifier) {
    val tracker: Tracker =
        (LocalContext.current.applicationContext as MatomoApp).getTracker()

    LaunchedEffect(Unit) {
        TrackHelper.track()
            .screen("/home")
            .title("Home")
            .with(tracker)

        tracker.dispatch()
    }

    Text(
        text = "Home screen",
        modifier = modifier
    )
}

If your app uses fragments

If your app uses fragments instead of composable destinations, you can add screen view tracking in the fragment lifecycle. Initialise the tracker in onViewCreated() and send the screen view in onResume() so it runs each time the fragment becomes visible. Each fragment should use a unique screen path and title.

Test goal tracking

After setting up screen view tracking, verify that each screen sends a screen view event when it becomes visible.

1. Run the app and navigate between screens.
   

2. In your Matomo instance, go to the Real-time dashboard or Visitors > Visits Log and confirm that the screen names you defined appear in the report.
   

Troubleshooting

If data does not appear, check the following:

1. The tracker is initialised in MatomoApp.kt and accessible from your composable using the application context.
2. Each screen calls TrackHelper.track().screen(...).title(...).with(tracker) inside a LaunchedEffect block so the screen view is sent when the composable becomes visible.
3. The Matomo instance URL and site ID in MatomoApp.kt are correct.
4. There may be a short delay before data appears in Matomo. Refresh the Real-time and Visits Log reports after a minute.

Next steps

You have now configured screen view tracking, ensuring that each composable or fragment is tracked when viewed. Continue refining your analytics setup by adding interaction tracking and conversion measurement. Explore additional Matomo SDK for Android guides to track button clicks, custom dimensions, and user IDs.