This guide describes a feature called User ID which lets you accurately measure your unique users across multiple devices.

About User ID

User ID is a feature in Matomo (Piwik) that lets you connect together a given user’s data collected from multiple devices and multiple browsers. In this guide you will learn how User ID works and the steps a developer must take to implement User ID on your website and/or app. As a result, when your users connect to your website or app on their smartphone, tablet and their laptop using your website’s « Login » feature, then Matomo will be able to connect together these visits and report them under the same unique user. Typically to implement User ID tracking, your users need to be able to login to your website.

Implementing User ID

In order to implement User ID on your website or app, you need a way to generate and/or assign a unique persistent ID to each of your users, and then you need to send this User ID along with the data being collected by Matomo.

What is a User ID string?

A User ID is typically a non empty string such as a username or email address or UUID that uniquely represents a user. For example these are all valid User IDs: and username and UID76903202. The User ID must be the same for a given user across all her devices and browsers.

How do I generate a User ID?

Typically your website will let users sign-in and once users are signed in then you know a unique User ID for this user: this may be her email address or her username or a random string such as UUID (Universally unique identifier).

User ID with the JavaScript client

You can set a User ID in JavaScript when measuring your websites, learn more in the Javascript Tracker Reference Guide.

User ID with another Tracker API client

If you are using an API Client such as the Android SDK or the PHP Client then you may call the function setUserId() and as a parameter set a non empty User ID string.

User ID with direct Tracker API access

If you are using the Tracker API directly you may set the User ID via the Tracker API parameter &uid=USER_ID.

User ID for WordPress websites

If your website is a WordPress site, you could use the WP-Matomo plugin to integrate Matomo to your site and easily enable User ID tracking. To enable User ID in WP-Matomo:

  1. Log in to WordPress as an admin
  2. If you are using WP-Matomo, click on « Settings »
  3. Click on « WP-Matomo »
  4. Click on « Enable Tracking » tab
  5. Scroll down to the bottom and in the « User ID Tracking » dropdown, choose for example « Email address ».

User ID report

To find the list of all Users and their User ID, in the menu in Matomo, click on: Visitors > User IDs.

The report lists all user ids and for each user the following metrics are displayed: Visits, Unique visitors, Users, Actions, Actions per Visit, Avg. Time on Website, Bounce Rate, Conversion Rate.

Benefits of User ID

  • View the User ID for each visit: the Visits Log and the User Profile both display the User ID on screen next to the IP address. This makes visualising users very convenient.
  • Easily segment your traffic to show one particular user: use a Custom Segment to display at once all the actions performed over time by a particular User on your website.
  • Get more accurate unique users count: by default Matomo cannot accurately track unique visitors across devices (each time a visitor switches to a new device to visit the website then a new visit and a new user will be counted). When setting User IDs though Matomo will be able to more accurately measure the number of unique visitors.
  • Analyse Logged in users VS Logged out users: by segmenting your traffic you can compare metrics for signed-in users VS users not signed in.

How requests with a User ID are tracked

When you specify a User ID for a given tracking request then Matomo will make sure to track this request in a new or existing visit from the specified User ID. Here are some example of how User ID works:

  • Same user from multiple device use case: In the case where a person connects to your website simultaneously from a laptop and a tablet and that you have correctly set a User ID on all devices, then the visitor’s requests across all devices will be tracked in the same Visit and the visitor will be tracked as a unique visitor. Result: one user, one visit, one unique visitor. (if User ID was not used then Matomo would have tracked two visits from two unique visitors).
  • When a visitor connects to your website and is not logged-in (User ID is not set) then a visit is created. If the visitor then logs-in your website and has a User ID set then their existing visit will be re-used (the visit without User ID that is created when the user was not logged in yet). All requests where this User ID is set will all be added into this same visit. Result: one user, one visit, one unique visitor. (if User ID was not used it would also have created one visit and one unique visitor).
  • Signing-out use case: In the case where a visitor visits your website and is logged-in (User ID is set) then a visit will be created for this User ID. If then visits logs out then the visitor has no User ID set any more and a new visit will be created on the page view right after logging out. (if User ID was not used then the requests would have been tracked into one visit and one unique visitor). Starting in Matomo 3.4.0 we introduce a new functionality to record a user logging out, via the method resetUserId, learn more about about When user logs out, reset User ID in the developer guide.

Replace User ID with a pseudonym

As a Super User, you can enable a feature to « Replace User ID with a pseudonym ». To enable this feature, go to Administration > Privacy > Anonymise your data.

When the option « Replace User ID with a pseudonym » is enabled (in the section « Anonymize Tracking Data »), the User ID will be replaced by a pseudonym in all data tracked going forward. This is useful to avoid directly storing and displaying personally identifiable information such as an email address. In technical terms: given your User ID, Matomo will process the User ID pseudonym using a salted hash function.

If you have before tracked User IDs and would like to now replace your existing historical User ID data by pseudonyms, you can do so: as Super User, you can anonymise previously tracked raw data in the same page Administration > Privacy > Anonymise your data.

Note: replacing with a pseudonym is not the same as anonymisation. In GDPR terms: the User ID pseudonym still counts as personal data. The original User ID could still be identified if certain additional information is available (which only Matomo and your data processor has access to).