How do I set the User ID using Matomo Tag Manager?

Cloud On-Premise

User ID tracking in Matomo links visits, actions, and conversions to a single identifier so you can recognise the same user across sessions, devices, and browsers.

The User ID setup and configuration depends on how Matomo is implemented: either through the JavaScript tracking code, Matomo Tag Manager, the WordPress plugin, or one of the Matomo SDKs.

This guide covers how to set up User ID tracking in Matomo Tag Manager using the mtm data layer.

Before you start

  • Your Tag Manager container must have a valid Matomo tracking tag, pageview trigger and Matomo configuration variable with the container snippet added to your site pages.
  • Your website should be set up to identify logged-in users, so the correct User ID is sent at login and cleared on logout. This requires a unique and persistent user identifier that represents each logged-in user.
  • When any personal identifier, it is recommended to update your Matomo privacy settings to use a pseudonym to replace the User ID for enhanced privacy. The User ID pseudonym is processed using a salted hash function.
  • If you operate in a region with privacy or consent requirements, ensure that sending User IDs is covered under valid consent before implementing this setup.

Configure Matomo Tag Manager

There are different ways to track logged-in users with Matomo Tag Manager. For example:

  • use a First-Party Cookie variable to read the user’s identifier in a first-party cookie set by your website,
  • use a Custom JavaScript variable to retrieve the identifier in the browser’s local storage, or
  • push user data to the mtm data layer and use a Data Layer variable to capture that value.

The following steps explain how to use the mtm data layer to record the User ID.

Create a data layer variable

Connecting your website’s login data to Matomo through a data layer variable involves creating a Data Layer Variable component in Tag Manager to capture the user identifier. Then you will need to update the Matomo Configuration Variable so the User ID is sent with each tracking request when the login event is pushed to the data layer.

  1. In Tag Manager, go to Variables and click Create New Variable.
  2. Provide a custom name e.g., User ID.
  3. Enter the Data layer variable name. This must be the same variable name that appears in your site’s code.
    create a data layer variable
  4. Click Create New Variable to save.

This variable will capture the user identifier whenever your site pushes it to the data layer.

Create or update the Matomo Configuration variable

Next, you’ll connect the Data Layer Variable to Matomo’s tracking configuration.

  1. Go to Variables and open the Matomo Configuration Variable used in your tracking tag (or create a new one with your Matomo site URL and site ID).
  2. Scroll down to the User ID field and select the data layer variable created earlier e.g., {{User ID}} and save the configuration.
    set user id in mtm
  3. Matomo Tag Manager will now automatically include the User ID in each tracking request whenever the variable is available.

Push the event to the data layer

Your website needs to send the user identifier to the data layer when a user logs in. This requires a adding a snippet to your site’s login logic. It must be placed immediately after successful user authentication.

In the example below, the event indicates that a login has occurred (user_login) and the userId is the key name used to store the user’s unique identifier and savedUser is the value provided by the site when the user logs in. The key name (userId) must match the Data Layer Variable Name defined in Matomo Tag Manager.

window._mtm = window._mtm || [];
window._mtm.push({
  event: 'user_login',
  userId: savedUser
});

Preview and publish the updated container

To test the User ID is being passed correctly to Matomo, use Preview Mode to confirm the setup:

  1. In Tag Manager, click Preview and enter your website URL and click Debug.
  2. A debug panel appears where you can view the Variables tab and verify that your User ID variable displays the expected value when a user logs in.
  3. You can also verify this in the browser developer tools (F12). Go to the Network tab and look for the request to matomo.php and confirm that the URL contains the uid parameter with your test User ID value.
  4. Open Matomo and navigate to Visitors > Real-time.
  5. Your User ID should appear in the Visits in real-time report and view the Visitor Profile containing the User ID.
    view real-time report with user id
  6. To test tracking anonymous sessions, log out of your website and reload the page.
  7. Check in the browser developer tools > Network tab that no uid parameter is included in the tracking request.
  8. In Matomo, the visit should not appear under a User ID in the Visits Log and Visitor Profile.

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.

Previous FAQ: Set up the Matomo Configuration Variable