Track goals with the Matomo SDK for Android

Goals represent user actions or outcomes in your app, such as completing a download or reaching a specific screen. By creating and tracking goals, you can measure conversions and evaluate how effectively your app supports key user journeys.

This guide explains how to track goals in your Android app using Matomo. The example uses a Jetpack Compose app, where interactions are handled within composable functions. Goal tracking is implemented using the TrackHelper.track().goal(goalId).with(tracker) method.

Before you start

1. 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.
2. Each goal must first be created in your Matomo instance under Goals > Manage Goals. For example, trigger a goal conversion when visitors view a specific page.
3. Take note of the numeric Goal ID required for configuring tracking in your mobile app. Learn how to create goals in Matomo.

Track a goal when a screen is viewed

The TrackHelper class is used to send individual tracking requests (hits), such as screen views, events, goals, and custom dimensions.

If a goal is viewing a specific screen (for example, the user Profile page or confirmation screen), add the goal tracking to the composable that represents that screen.

1. Go to the kotlin/ (or java/) directory and open the file that defines the composable screen where the goal conversion should be tracked, for example ProfileScreen.kt.
2. Ensure the file composable has the required imports (added at the top of the file):
   import androidx.compose.runtime.LaunchedEffect
import androidx.compose.ui.platform.LocalContext
import org.matomo.sdk.Tracker
import org.matomo.sdk.extra.TrackHelper
3. Retrieve the tracker instance inside the composable using the global instance defined in MatomoApp.kt.
4. Add the goal tracking call inside a LaunchedEffect block so the goal is triggered when the Profile screen becomes visible.
5. If you are also tracking a screen view, keep both calls in the same LaunchedEffect block.

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

    LaunchedEffect(Unit) {
        // Track screen view
        TrackHelper.track()
            .screen("/profile")
            .title("Profile")
            .with(tracker)

        // Track goal when the screen is viewed
        TrackHelper.track()
            .goal(1)
            .with(tracker)

        tracker.dispatch()
    }

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

Track a goal when a button is clicked

If a goal represents a user action (for example, clicking a download button), trigger the goal inside the button’s onClick handler.

The sample code below tracks the goal conversion when the Download button is pressed on the Home screen.

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

    Column(modifier = modifier) {

        Button(
            onClick = {
                // Track button click event
                TrackHelper.track()
                    .event("Button", "Click")
                    .name("Download-btn")
                    .with(tracker)

                // Track goal conversion (e.g. download started)
                TrackHelper.track()
                    .goal(2)
                    .with(tracker)

                tracker.dispatch()

                // Add navigation or download logic here if required
            }
        ) {
            Text("Download")
        }
    }
}

Test goal tracking

After configuring tracking, verify that goal conversions are recorded when the trigger occurs.

1. Run the app.
2. If the goal is based on a screen view, navigate to the screen that triggers the goal.
3. In your Matomo instance, go to the Real-time dashboard or Visitors > Visits Log and confirm that a goal conversion appears in the report.
   
4. If the goal is based on a button click, press the tracked button and view the Visits Log.
   
5. After the reports have processed, go to Conversions > Goals to analyse goal completions and conversion rates.

Troubleshooting

If goal 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. The goal tracking code is implemented in the correct location:
   • inside a LaunchedEffect block for screen-based goals.
   • inside an onClick handler for action-based goals.
3. The goal ID used in TrackHelper.track().goal(goalId) matches the goal configured in your Matomo instance.
4. The Matomo instance URL and site ID in MatomoApp.kt are correct.
5. If the goal is triggered by a button that also performs navigation or another action, ensure the goal is tracked before the subsequent action occurs.

Explore additional Matomo SDK for Android guides to track button clicks, custom dimensions, and user IDs.