Matomo includes a User ID feature for enhanced tracking on websites that offer the ability for visitors to log in. This feature enables website owners to connect a unique identifier, such as each visitor’s username or email, with their analytics data for more accurate tracking. By tracking the User ID it is possible to connect visitors between visits across multiple dates and devices.

Benefits of Enabling User ID Tracking

One of the main benefits of tracking User IDs with Matomo is it improves the accuracy of unique visitor counts for your site. It does this by accurately identifying the same user across multiple visits from different devices. However, that is not all it does! There are several useful reports made available when User ID tracking is enabled, which can provide additional insights about your logged in visitors.

  • Understand where users are getting stuck on your site – You can easily segment your visits to show one particular user. This can help you to offer customer support if people are encountering challenges while navigating your site.
  • More accurate unique visitor counts – Matomo uses several heuristics to determine whether a visit is unique or not. However, User ID tracking is one of the most effective for tracking the same user across different devices and locations over time.
  • Learn what specific users are doing – You can show the Visits Log for specific users via their User ID. Look up a specific visitor’s User ID to see everything they have done on your site, across all of their visits. This is especially useful for providing customer support or performing security audits for a site.
  • View a full User Profile for specific users – Useful for market research. You can build a full profile of each user to see: how much time they spend on your site, where they access it from, and their lifetime Ecommerce value.
  • Get a list of your most engaged users – This can help you understand who your most engaged users are. You can also sort these tables by different metrics to see if, for example, the people spending the most time on your site are the same ones with the highest spend.

How To Set Up User ID Tracking in Matomo

To enable User ID functionality, you need to start sending User IDs to Matomo. First, you will need to identify what data your site holds for each user that can be used as a User ID. Every website system that allows people to log in should have at least one unique identifier that it uses to differentiate between users. This may be a unique number, a username, or simply a user’s email address.

It is recommended you set a user’s email address as a User ID if you can. This is because it will also allow you to track the same user when they complete a contact or subscription form, even while they are logged out.

The next step is to send this unique identifier through to Matomo Analytics. The exact method for doing this will vary depending on how your site was built. You can find step-by-step instructions for the various methods below.

How to Configure User ID Tracking for WordPress

If you are using WordPress, there are two main ways to integrate with Matomo. The first is with the official Matomo for WordPress plugin, which is where Matomo lives entirely inside your WordPress installation. In this case, you can follow the Matomo for WordPress guide below.

Alternatively, if you are using Matomo Cloud or Matomo On-Premise, you will likely be using the WP-Matomo plugin to integrate WordPress. In this case, the steps you need to follow are shown in the second guide listed below.

Note: WordPress users can typically change their email address, but not their username. When selecting a unique identifier in the guides below, select Username if you want the most reliable long-term identifier. However, if you also want to capture a User ID from form submissions of logged out users too, you should use Email Address instead.

Matomo for WordPress: How to Enable User ID Tracking

  1. Log in to your WordPress dashboard with an admin account.
  2. Hover over Matomo Analytics in the menu and click Settings within the sub-menu.
  3. Scroll down to the User ID dropdown and select Email Address or Username.
  4. Click the blue Save Changes button below, and User ID tracking will be enabled.

WP-Matomo: How to Enable User ID Tracking

  1. Log in to your WordPress dashboard with an admin account.
  2. Hover over Settings in the menu and click on WP-Matomo or WP-Piwik depending on which version you have installed.
  3. Click on the Enable Tracking tab.
  4. Enable a non-manual tracking method in the Add tracking code setting.
  5. Scroll down to the User ID Tracking setting and select Email Address or Username in the dropdown.
  6. Click the blue Save Changes button, and User IDs will begin tracking immediately.

How to Configure User ID Tracking with Matomo Tag Manager

The method for configuring User ID tracking with Matomo Tag Manager will vary depending on how your website has been built. As there is no standardised way of including User IDs within your website code, you will likely need to set this up yourself or get developer assistance.

  1. Install and configure Matomo Tag Manager for your site.
    Learn more about getting started with Matomo Tag Manager.

  2. Create a variable called UserID that captures each visitor’s unique user identifier.
    If you display usernames on the front-end of your site, you may want to create a variable from a HTML DOM selector whilst a user is logged in. Or, for a more flexible method, you can configure your website to expose a user’s unique identifier, such as an email address, to the data layer with a little custom code.

  3. Create or update your Matomo Configuration variable to collect the UserID.
    Assuming you named your User ID variable in the last step UserID, you would scroll down to the User ID text field and input {{UserID}} to pull the values captured by that variable into your Matomo tracking configuration.

  4. Preview and publish your updated Matomo container.
    While previewing, you can visit your website and a Matomo Tag Manager debug screen will show at the bottom half of your screen. You can click the Variables tab within this to ensure the UserID variable is being picked up correctly by Matomo Tag Manager. Once confirmed, publish your container to begin tracking User IDs.
    Matomo Tag Manager Container Preview

How to Send User ID with the JavaScript Client

If you have a completely custom website, you can add a JavaScript snippet of code to your website which sends the User ID to Matomo via the Javascript Tracking API. To do this, you would add the unique identifier for a user to the following snippet of code:

_paq.push(['setUserId', 'USER_ID_HERE']);

The example above, _paq.push([ ]); sends the data to Matomo. 'setUserId' defines what data is being sent, and you should configure the second argument 'USER_ID_HERE', to dynamically contain the unique User ID of the visitor currently viewing the page. This code should be placed within your Matomo tracking code, above the action that you are tracking.

For example, the code above within the standard Matomo pageview tracking code would look a little something like this:

<!-- Matomo -->
<script type="text/javascript">
  var _paq = window._paq = window._paq || [];
  _paq.push(['setUserId', 'USER_ID_HERE']);
  (function() {
    var u="//{$MATOMO_URL}/";
    _paq.push(['setTrackerUrl', u+'matomo.php']);
    _paq.push(['setSiteId', {$IDSITE}]);
    var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
    g.type='text/javascript'; g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
<!-- End Matomo Code -->

For more details on this method, consult the developer documentation on User IDs.

How to Send User ID with Matomo SDKs

There are several Matomo Software Development Kits (SDK) available for use in apps. If you are using one of these, for example, the iOS SDK or Android SDK, you typically need to call the API function setUserId() with the User ID as a parameter. Alternatively, you may also be able to make use of the Tracking HTTP API.

Analysing User ID Reports

You can access the User IDs report within the Visitors section of the main navigation within Matomo. This report will show you a table of all registered User IDs that have interacted with your site during the selected reporting period. It also shows the number of visits and actions completed by each user, as well as, whether or not the user converted at least one goal.

Matomo User ID Table

The User IDs table can also be updated to include more engagement metrics. To do this, hover your mouse over the table so the icons menu appears in the bottom left. Then click on the table icon Table Icon to reveal the alternative visualisation options. Then click on Display a table with Visitor engagement metrics. This will update the report to include additional columns so you can analyse the following metrics in one view:

  • Visits – How many times did each user visit your site within the reporting period?
  • Actions – How many actions have they taken on your site? This could include page view, searches, downloads or clicks on your links to external sites.
  • Actions Per Visit – How many of these actions did they take on an average visit?
  • Avg Time on Website – What is the average amount of time the user spent on your site for each unique visit?
  • Bounce Rate – The percentage of the users’ visits where they only viewed a single page.
  • Conversion Rate – The percentage of the users’ visits where they completed a Goal.

The above statistics are useful for analysing your groups of users, but it is also possible to get even more granular data for a single user. If you hover your mouse over any of the User ID rows, you will see three green icons appear. Clicking on any of these will allow you to dig even deeper into visits by that user.

User ID Row Menu

View Visitor Profile

When you click on the user profile icon User Profile Icon a Visitor Profile will load containing extended details about a user. It features details such as their location, device and browser usage, number of visits, any custom dimensions or variables, Ecommerce value, and a full breakdown of their visits to your site. This feature can help you build customer profiles to identify where you may be able to offer more value.

User ID: Visitor Profile

Open Segmented Visits Log

Clicking on the segmented visits log icon Segmented Visits Log Icon displays a paginated log of all visits associated with the unique User ID. User IDs stored without pseudonyms can be helpful for customer support to debug where a specific user might be encountering issues on your site.

User ID Visits Log

Open Row Evolution

Click on the row evolution icon Row Evolution Icon to load an Evolution Graph, where you can explore the user’s engagement over time. You should also keep an eye out for potential issues on your site. For example, if you notice dips in traffic trends that coincide with annotated changes on your website.

User ID Row Evolution

How to use User IDs to Create a “Logged In” Segment

Segments are a powerful tool for analysing groups of visitors to your site based on specific criteria. When paired with the User ID feature, you can easily create a segment based on logged in users. The first step is to make sure you only allocate User IDs to registered and logged in visitors on your site. From there, you can use the standard segment builder to check for the presence of a User ID to determine whether a visitor is logged in or not.

Logged In User Segment

This segment can be useful for analysing whether logged in users interact with your site differently from logged out users. It can also help you understand trends for what is likely to be your most valuable users.

User ID Privacy Considerations

When you enable User ID tracking, you associate a persistent identifier with a user so you can recognise their visits across different devices and visits. As User IDs precisely track specific users on your site, this feature has significant implications for user privacy. While using this feature, you will likely require consent from your users under regulations such as the GDPR.

Configuring Matomo to replace User ID with a pseudonym

To increase privacy, User IDs can be used in a mode where personally-identifying information (PII) is obscured for more general analysis. Due to the nature of User IDs, you can’t completely anonymise the records. However, you can configure Matomo to replace the User IDs with pseudonyms – unique random identifiers – to respect user privacy. These pseudonyms are shown in your analytics instead of their primary User ID so you can analyse individual users without revealing their email or username. For example, you might see ac0868489d8e413180129595fa9d177196c7533d instead of as the user ID.

How User ID Pseudonyms are Generated

Because User IDs need to be connected to a specific user, they cannot be truly random. Instead, the unique identifiers are passed through something called a cryptographic hash function. This is a deterministic function that will always generate the same seemingly random number when presented with the same input.

To further protect the User IDs, Matomo also adds something called a salt to the initial User ID, which is a random set of characters unique to your installation. This means the hash function result is based on the combined User ID and secret salt. This protects against a potential issue, where somebody could run the hash function with a known User ID to see if it creates the same pseudonym.

How to Enable User ID Pseudonyms in Matomo

To enable the use of pseudonyms for User IDs in Matomo, you need to update your privacy settings.

  1. Log in to your Matomo Dashboard.
  2. Click on the cog icon in the Top Menu.
  3. Under the Privacy section of the Main Navigation, click Anonymize data.
  4. Within the Anonymize Tracking Data section, you will see a checkbox setting labelled Replace User ID with a pseudonym which you should enable.
  5. Click the big Save button, and all future visits will be pseudonymised.

Note: The above steps only apply the pseudonym to visits after you have enabled this setting. If you would like to apply it retroactively to the User ID data you have already collected, then read on…

How to Apply Pseudonyms to Existing User IDs in Matomo

There may be situations where you have been collecting full User IDs in Matomo but no longer want to hold that data. Perhaps due to a change in local regulation or simply a desire to enhance user privacy. Whatever the reason, Matomo provides a feature that allows you to replace User IDs already captured with pseudonyms.

  1. Log in to your Matomo Dashboard.
  2. Click on the cog icon in the Top Menu.
  3. Under the Privacy section of the Main Navigation, click Anonymize data.
  4. Scroll down to the Anonymize previously tracked raw data section.
  5. Select the website you would like to process in the first dropdown menu. The default selection will process data for all sites, so you can choose to leave it at that.
  6. Select the date range you would like to process by entering the start and end dates in the text fields below. The dates should be entered in YYYY-MM-DD format.
  7. Click the Replace User ID with a pseudonym checkbox to enable it.
  8. Click the big Anonymize Past Data for The Selected Site and Time button.

The above process can take a while to process after finishing so you will not be able to confirm this has worked immediately. While the job is processing, you can follow the status at the bottom of the page. Once complete, you may want to check the Visitors > User IDs report in your Matomo Dashboard to ensure no user IDs remain.

Useful Ways to Benefit from the User ID Feature

The User ID feature helps you make your analytics data more actionable on an individual user basis. Here are some quick ideas for how you can use this feature to benefit the goals for your website:

  • Membership Sites – Rank your users, understand what content each specific user is interested in, categorise the capabilities of various users of your site, look for sticky content i.e. content that people keep coming back to.
  • Market Research – Build a profile of the different types of users using your site and their relevant interests.
  • Customer Support – If users contact you after having trouble accessing certain content or download, look at where they are getting stuck.
  • Reward Engaged Users – Being able to identify your most engaged users enables you to target these users with additional outreach and campaigns to build lasting relationships. You can check the login frequency of specific users to see who is most active.
  • Login State Segments – Look into the behavioural and ecommerce trends of logged in users vs logged out users.
  • Identify Unengaged Customers – Identify your least engaged users which are most likely to churn and run tests to see if you can re-engage them.
  • Analyse differences between cohorts of your users – For example, if you have raised your pricing, do users that have joined after the price rise seem to interact with your site any differently from those on an older price plan?

How to Compare Analytics of Logged In vs Logged Out Users

One indirect way to benefit from the User ID feature is to create segments based on a user’s login state. You can create segments for visits based on whether they are associated with a User ID or not and compare the activity of these two groups of users.

How to Create a Segment for Logged in Users

  1. Click on the Segment button.
  2. Type Logged In Users.
  3. Select User ID in the first dropdown.
  4. Select Is not in the second dropdown.
  5. Leave the text field blank.
  6. Click the big Save & Apply button.

How to Create a Segment for Logged Out Users

  1. Click on the Segment button.
  2. Type Logged out Users.
  3. Select User ID in the first dropdown.
  4. Select Is in the second dropdown.
  5. Leave the text field blank.
  6. Click the big Save & Apply button.

How to compare the two segments

Once you have created the two segments, you can compare them in any of the Matomo reports.

  1. Click the Segment button.
  2. Select the Logged In Users segment.
  3. Click the Segment button again.
  4. Click the Comparison icon Comparison Icon next to the Logged Out Users segment.
  5. Visit any Matomo report where you would like to compare the two segments and see the data for each, side-by-side.