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 the same user ID as in your CMS, CRM or sales system. 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, they 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.
  • This setup is for websites only. If you want to set up a user ID for mobile, use our SDKs: Android, Flutter, React Native, iOS.

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 to the app and we have their customerId available in a data layer.

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. Let’s say a visitor logs into a banking app.
    set up user id logged into app
  2. In the data layer, we’ve got the following information:
    <script>
        window.dataLayer = window.dataLayer || [];
        window.dataLayer.push({
            'customerId': 'ABC123',
            'app' : 'banking app',
            'plan': 'basic'
        });
    </script>
  3. We can use customerId from this data layer as our user ID.
  4. We’ll set up a data layer variable that will pull out information about customerId.
  5. Go to Menu > Tag Manager.
  6. Navigate to Variables.
  7. Click Add a variable.
  8. Name the variable: Customer ID.
  9. Select the following variable type: Data layer.
  10. In Data layer variable name, type: customerId.
    data layer variable name
  11. Click OK.
  12. Test your variable in debug mode.
  13. When you’re happy with how the variable works, click Publish.
  14. Navigate to Tags.
  15. On the left, click Piwik PRO.
  16. In Data collection, toggle Set a user ID.
  17. Type in a variable that you set in previous steps. In our case, the variable is {{ Customer ID }}.
    data collection variable name
  18. When your’re done, click Save for the tag.
  19. Test your tag in debug mode.
  20. 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 to the app and their customerId isn’t available in a data layer 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. Let’s say a visitor logs into a banking app.
    set up user id logged into app
  2. In the data layer, we’ve got the following information:
    <script>
        window.dataLayer = window.dataLayer || [];
        window.dataLayer.push({
            'customerId': 'ABC123',
            'app' : 'banking app',
            'plan': 'basic'
        });
    </script>
    
  3. We can use customerId from this data layer as our user ID. 
  4. We’ll set up a data layer variable that will pull out information about customerId
  5. Go to Menu > Tag Manager.
  6. Navigate to Variables.
  7. Click Add a variable.
  8. Name the variable: Customer ID.
  9. Select the following variable type: Data layer.
  10. In Data layer variable name, type: customerId.
    data layer variable name
  11. Click OK.
  12. Test your variable in debug mode.
  13. When you’re happy with how the variable works, click Publish.
  14. Navigate to Tags.
  15. Click Add a tag.
  16. Name the tag and choose the following type: Custom code (async).
  17. Click Next.
  18. In Tag code, type the following code:
    <script>
       _paq.push(['setUserId', '{{ Customer ID }}']);
       _paq.push(['ping']);
    </script>
    • _paq.push(['setUserId', '{{ Customer ID }}']);: This sets a variable Customer ID as the user ID.
    • _paq.push(['ping']);: This sends the user ID to the tracker.
    tag code
  19. In Tag triggers, click Add a trigger.
  20. Name the tag and select the following type: Page view.
    Setting up a user ID in Piwik PRO
  21. In Event conditions, define the following condition: Customer ID is not empty.
    event conditions
  22. When you’re done, click OK for the trigger
  23. Click Save for the tag.
  24. Test your tag in debug mode.
  25. When you’re happy how the tag works, click Publish.

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 code (async) 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.

For developers: For more information on the user ID, read our developer guides.

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