This guide describes a feature called User ID which lets you accurately measure your unique users across multiple devices.

About User ID

User ID is a feature in Piwik that lets you connect together a given user’s data collected from multiple devices and multiple browsers. In this guide you will learn how User ID works and the steps a developer must take to implement User ID on your website and/or app. As a result, when your users connect to your website or app on their smartphone, tablet and their laptop then Piwik will be able to connect together these visits and report them under the same unique user.

Implementing User ID

In order to implement User ID on your website or app, you need a way to generate and/or assign a unique persistent ID to each of your users, and then you need to send this User ID along with the data being collected by Piwik.

What is a User ID string?

A User ID is typically a non empty string such as a username or email address or UUID that uniquely represents a user. For example these are all valid User IDs: user@example.org and username and UID76903202. The User ID must be the same for a given user across all her devices and browsers.

How do I generate a User ID?

Typically your website will let users sign-in and once users are signed in then you know a unique User ID for this user: this may be her email address or her username or a random string such as UUID (Universally unique identifier).

User ID with the JavaScript client

You can set a User ID in JavaScript when measuring your websites, learn more in the Javascript Tracker Reference Guide.

User ID with another Tracker API client

If you are using an API Client such as the Android SDK or the PHP Client then you may call the function setUserId() and as a parameter set a non empty User ID string.

User ID with direct Tracker API access

If you are using the Tracker API directly you may set the User ID via the Tracker API parameter &uid=USER_ID.

Benefits of User ID

  • View the User ID for each visit: the Visitor Log and the User Profile both display the User ID on screen next to the IP address. This makes visualising users very convenient.
  • Easily segment your traffic to show one particular user: use a Custom Segment to display at once all the actions performed over time by a particular User on your website.
  • Get more accurate unique users count: by default Piwik cannot accurately track unique visitors across devices (each time a visitor switches to a new device to visit the website then a new visit and a new user will be counted). When setting User IDs though Piwik will be able to more accurately measure the number of unique visitors.
  • Analyse Logged in users VS Logged out users: by segmenting your traffic you can compare metrics for signed-in users VS users not signed in.

How requests with a User ID are tracked

When you specify a User ID for a given tracking request then Piwik will make sure to track this request in a new or existing visit from the specified User ID. Here are some example of how User ID works:

  • Same user from multiple device use case: In the case where a person connects to your website simultaneously from a laptop and a tablet and that you have correctly set a User ID on all devices, then the visitor’s requests across all devices will be tracked in the same Visit and the visitor will be tracked as a unique visitor. Result: one user, one visit, one unique visitor. (if User ID was not used then Piwik would have tracked two visits from two unique visitors).
  • Signing-in use case: In the case where a person connects to your website and is not logged-in (User ID is not set) then a new visit will be created. If the visitor then logs-in your website and has a User ID, then all requests from this User ID will be recorded in this user’s visit. Result: one user, two visits, two unique visitors. (if User ID was not used then the requests would be tracked into one visit and one unique visitor).
  • Signing-out use case: In the case where a visitor visits your website and is logged-in (User ID is set) then a visit will be created for this User ID. If then visitor logs out then the visitor has no User ID set any more and a new visit will be created on the page view right after logging out. (if User ID was not used then the requests would have been tracked into one visit and one unique visitor).

Resources