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: Starting in Matomo 3.13.0, when 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 separate Visits and the visitor will be tracked as multiple unique visitors, each with the same User ID. Result: one user, two simultaneous visits, two unique visitors. (if User ID was not used then Matomo would have tracked two visits from two unique visitors as well, but the user ID linking them would not be set). (Before Matomo 3.13.0, these visits would have been merged with a single visitor ID. This was changed to allow both devices and differing visit information to be seen separately.)
  • 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 the user then logs out and has no User ID set any more (resetUserId function is called), a new visit will not be created for the page views after logging out. Subsequent pageviews will still be tracked in the existing visit, and this visit will still have the User ID set. You can also easily force a new visit to be created when users log out, learn more in the developer guide for JavaScript Tracking: when user logs out, reset User ID

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).