Set up a user ID

Necessary tools: Analytics + Tag Manager

The user ID feature is one of the method used to recognize visitors on your website. It can be applied when your website or app has a mechanism to strictly recognize the visitor. In other words, you can capture a trustworthy ID, for example, an email, user name or other ID.

After setting up the user ID feature, the UserID is used as a single source of truth.

Before you start

Here are some things to know about the user ID before you begin working with it:

  • With UserID you can recognize a visitor across many devices. For example, when a visitor is logged in and switches between a laptop, mobile, and tablet, he or she will be seen as the same visitor.
  • When the visitor logs out and the UserID value is no longer available, he or she will be tracked as a new visitor and Piwik PRO will use the cookie as a source of information.

Set up a user ID

In this example, we’ll show you how to add a user ID when a visitor is logged in with an an email, and the email is available on all pages.

To set up a user ID, follow these steps:

  1. Find an ID on the page. For example, we’ll find a visitor’s email address.
  2. An example of visitor ID on the Clear Bank website.
  3. Inspect an element to see the code. In our case, the code is: <span id="email"></span>.
  4. The code has an id element email so we’ll use it to set a variable in Tag Manager. A variable will grab information about an id from the website, and it’ll pass it to the user ID feature.
  5. Log in to Piwik PRO.
  6. Go to Menu > Tag Manager.
  7. Navigate to Variables.
  8. Click Create new variable.
  9. Name the variable.
  10. Select a variable type. In our example, it’ll be DOM element.
  11. A variable with visitor's email in Piwik PRO.
  12. Set additional elements. In our case, we’ll set an element ID to email.
  13. A variable with visitor's email in Piwik PRO.
  14. Click Save.
  15. Navigate to Tags.
  16. Pick Piwik PRO tag from the left-hand list.
  17. Toggle Set user ID.
  18. A user ID feature in Piwik PRO.
  19. Type in a variable that you set in previous steps. In our case, the variable is {{Visitor email}}.
  20. A user ID feature in Piwik PRO.
  21. When your’re done, click Save for the tag.
  22. Test your tag in debug mode
  23. When you’re happy how the tag works, click Publish.

Set up a user ID manually

If for some reason you are unable to use automatic setup in Tag Manager, you’ll need to add user ID  feature manually to the tracking code.

To add a user ID manually, follow these steps:

  1. In your tracking code, find _paq.push(['trackPageView']);.
  2. Add the following code right before _paq.push(['trackPageView']);
_paq.push(['setUserId', 'USER_ID_HERE']);

Note: Replace USER_ID_HERE with a correct value.

Was this article helpful?

Be the first to rate this article.

Technical Support

If you have any questions, drop us a line at

We’re happy to help!