Track custom dimensions with Matomo SDK for Android

In addition to standard screen views, events, and goals, the Matomo Android SDK supports tracking more advanced data types such as Custom Dimensions, User IDs, and Campaigns.

This guide explains how to track action and visit Custom Dimensions in your Android app using Matomo. The example uses a Jetpack Compose app, where interactions and tracking are implemented within composable functions.

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. Create the custom dimension in Matomo and note the numeric dimension ID. Learn how to create Custom Dimensions.
3. Custom dimensions add context to your tracking data. Use an action dimension to describe a specific interaction or screen. For broader context (for example, user type), use a visit dimension, which applies across the session.

Track an action custom dimension

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

1. Go to your project in Android Studio and open the composable where you want to attach the dimension, for example HomeScreen.kt.
2. To categorise where an interaction occurs, add an action dimension to an event, inside the onClick handler. The .dimension() method must be called before .event().
3. In this example, a Contact us button appears across multiple screens. When the button is pressed, the custom dimension captures the Page Title so you can identify the page where users clicked the button.

Button(
    onClick = {
        TrackHelper.track()
            .dimension(1, "contact_CTA")   // set the dimension first
            .event("Button", "Click")
            .name("Contact us")
            .with(tracker)

        tracker.dispatch()
         // Open contact page
   }
)

Add an action dimension to a screen view

1. You can also attach an action dimension to a screen view to describe the type of page.
2. In this example, the Profile screen is categorised as a User page.

LaunchedEffect(Unit) {
        TrackHelper.track()
            .dimension(3,"User page") // set the dimension first
            .screen("/profile")
            .title("Profile")
            .with(tracker)


        tracker.dispatch()
    }

Track a visit custom dimension

Visit dimensions apply to the entire session.

1. Set the dimension on the tracker so they are automatically included in all subsequent hits (screen views, events, and goals).
2. For example, add it in MainActivity.kt when the value depends on runtime state, such as login status or subscription plan:

val tracker: Tracker = (applicationContext as MatomoApp).getTracker()

TrackHelper.track()
    .dimension(2, "premium_plan")
    .event("Login", "Success")
    .name("Login")
    .with(tracker)

tracker.dispatch()

Test custom dimension tracking

After configuring tracking, verify that dimension values are recorded with your tracking data.

1. Run the app.
2. If the dimension is attached to an event, press the tracked button (for example, “Contact us”).
3. In your Matomo instance, go to the Visitors > Visits Log. Hover the mouse over the entries to view the custom dimension value.
   
4. To test a visit dimension, perform the action that sets the value (for example, log in with subscription status) and navigate to a screen.
5. The expected dimension value (for example, Premium Plan) should appear in the report.
   

Troubleshooting

If the dimension data does not appear, check the following:

1. The correct dimension ID is used in the tracking code.
2. The dimension is attached to the correct action (screen view or event).
3. For visit dimensions, the value persists across multiple hits in the same visit.
4. Custom dimensions are only recorded when a tracking request is sent. Ensure the dimension is added before .screen(), .event(), or .goal() so it is included in the request.

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