Set up a user ID

Analytics + Tag Manager

Needed permissions: owner, manage or edit & publish

A user ID is a piece of additional information about the visitor that can be collected on your website. It can be a visitor’s email, username or another identifier. You can use it to create a segment and see all sessions of one visitor. In some cases, it is also used to recognize a returning visitor.

Before you start

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

  • With the user ID 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.
  • The user ID helps to attribute sessions to the visitor and is sometimes treated as a last resort identification mechanism, for example when the visitor has disabled cookies.
  • If the user ID is set for a visitor, its value overwrites the visitor ID, but it doesn’t serve as a mechanism for joining sessions in cross-device tracking. Sessions from various devices are split to get a clearer picture of user behavior.

Set up a user ID (when it’s present on every page)

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

Note: Use this method only when you can access a user identifier on every page of your website. If the identifier isn’t available at some point, the tracker will assign an empty value to the user ID, which will cause data inconsistency. If you’re not sure that a user identifier is available everywhere, follow the method described in the next section.

  1. Find an ID on the page. For example, we’ll find a visitor’s email address.
    Setting up a user ID in Piwik PRO
  2. Inspect an element to see the code. In our case, the code is: <span id="email">joe.doe@work.com</span>.
  3. 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.
  4. Log in to Piwik PRO.
  5. Go to Menu > Tag Manager.
  6. Navigate to Variables.
  7. Click Add new variable.
  8. Name the variable. In our case, we’ll name it Visitor email.
  9. Select a variable type. In our example, it’ll be DOM element.
    Setting up a user ID in Piwik PRO
  10. Set additional elements. In our case, we’ll set an element ID to email.
    Setting up a user ID in Piwik PRO
  11. Click OK.
  12. Navigate to Tags.
  13. On the left, click Piwik PRO.
  14. In Data collection, toggle Set a user ID.
    Set a user ID in Piwik PRO
  15. Type in a variable that you set in previous steps. In our case, the variable is {{Visitor email}}.
    Set a user ID in Piwik PRO
  16. When your’re done, click Save for the tag.
  17. Test your tag in debug mode.
  18. When you’re happy how the tag works, click Publish.

Set up a user ID (when it’s not present on every page)

In this example, we’ll show you how to add a user ID when a visitor is logged in with an email, and the email isn’t available everywhere on your website. For that, we’ll use a custom tag that will capture the user ID only if it is present and pass it to the tracker.

Note: Use this method when you can’t access a user identifier on every page of your website. It will prevent the tracker from assigning an empty value when the user ID isn’t available.

  1. Find an ID on the page. For example, we’ll find a visitor’s email address.
    Setting up a user ID in Piwik PRO
  2. Inspect an element to see the code. In our case, the code is: <span id="email">joe.doe@work.com</span>.
  3. 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.
  4. Log in to Piwik PRO.
  5. Go to Menu > Tag Manager.
  6. Navigate to Variables.
  7. Click Add new variable.
  8. Name the variable. In our case, we’ll name it Visitor email.
  9. Select a variable type. In our example, it’ll be DOM element.
    Setting up a user ID in Piwik PRO
  10. Set additional elements. In our case, we’ll set an element ID to email.
    Setting up a user ID in Piwik PRO
  11. Click OK.
  12. Navigate to Tags.
  13. Click Add new tag.
  14. Name the tag and choose the following type: Custom asynchronous tag.
  15. Click Next.
  16. In Tag code, type the following code:
    <script>
    _paq.push(['setUserId', '{{Visitor email}}']);
    _paq.push(['ping']);
    </script>
    • _paq.push(['setUserId', '{{Visitor email}}']);: This sets a variable Visitor email as the user ID.
    • _paq.push(['ping']);: This sends the user ID to the tracker.
    Code for setting a user ID in Piwik PRO
  17. In Tag triggers, click Add new trigger.
  18. Name the tag and select the following type: Page view.
    Setting up a user ID in Piwik PRO
  19. In Event conditions, define the following condition: Visitor email is not empty.
    Setting up a user ID in Piwik PRO
  20. When you’re done, click OK for the trigger
  21. Click Save for the tag.
  22. Test your tag in debug mode.
  23. When you’re happy how the tag works, click Publish.

Optionally, instead of setting it up in the described way, you can use this code in a custom tag fired on all page views:

var my_userid_element = document.querySelector("#email");

if (my_userid_element){
    var userid_for_piwikpro = my_userid_element.textContent.trim();
    if (userid_for_piwikpro.length>0){
        _paq.push(['setUserId',userid_for_piwikpro]);
        _paq.push(['ping']);
    };
};

Note: Use the correct value in document.querySelector("#email"). We’re showing an example for a CSS element defined as email.

Reset a user ID

In some cases, you may need to reset a user ID. For example, when a visitor logs out and continues browsing your website, you may not want to send requests with the ID to the tracker anymore.

To reset a user ID, follow these steps:

  1. Create a custom asynchronous tag with the following code:
    <script>
            _paq.push(['resetUserId']);
    <script>

    Note: In this case, we don’t need to send a ping request because after applying this method, the user ID won’t be in the tracker, and all future events won’t have the user ID string.

  2. Create a trigger to fire this tag under desired conditions. For example, when a visitor logs out.

Was this article helpful?

Technical support

If you still have some questions, visit our community.
There’s always someone ready to help!

Back to help center