Set up User ID tracking with Matomo SDKs

Matomo provides SDKs for multiple environments, including JavaScript, Android and iOS, developed by the Matomo team and open-source community. All SDKs integrate with the Matomo Tracking HTTP API and lets you to associate tracking data with a specific user by setting a User ID after user login authentication succeeds. Matomo can then recognise returning users and link their actions across different sessions and devices. Learn more about User ID tracking.

This guide covers setting up User ID tracking with the Matomo SDKs for Android and iOS.

Matomo Android SDK

Before setting a User ID, the Matomo tracker must already be configured and initialised in your app, usually in the custom application class (for example, MatomoApp.kt). This ensures all subsequent hits use the same tracker instance. Once the tracker is available in your Android app, you can assign a User ID to associate visits with a logged-in user based on your custom authentication logic.

Add the following line in the fragment where the user logs in or when their session starts:

tracker.userId = "user_12345"

Replace the value with your app’s user identifier. From that point, all tracked screen views, events, and goals will be linked to that User ID until it’s cleared.

Matomo iOS SDK

Before setting a User ID, the Matomo tracker must already be configured and initialised in your app, typically in the AppDelegate or within an initial setup function that creates the shared tracker instance. This ensures all subsequent hits use the same tracker configuration. Once the tracker is available in your iOS app, you can assign a User ID to associate visits with a logged-in user based on your authentication logic.

Add the following line after the user logs in or when their session begins:

matomoTracker.userId = "user_12345"

Replace the value with your app’s unique, anonymised user identifier. From that point, all tracked screen views, events, and goals will be linked to that User ID until it’s cleared.

Matomo JavaScript tracker

When using the Matomo JavaScript tracker on a website or web app, you call the setUserId() function with the User ID as a parameter. This associates all subsequent tracking data with that user instead of an anonymous visitor. Read the [User ID tracking setup guide using the JavaScript tracker]

Once User ID tracking is configured, you can measure customer engagement, compare logged-in and anonymous behaviour, and analyse user journeys across all Matomo reports. Use the Reporting API, create Segments, track conversions, and include the User ID dimension in Custom Reports.