Opened 18 months ago

Last modified 23 hours ago

#3490 new New feature

Accurate User Detection cross devices: User ID (set in JS and all other clients)

Reported by: matt Owned by:
Priority: critical Milestone: 2.x - The Great Piwik 2.x Backlog
Component: Core Keywords:
Cc: tsteur Sensitive: no

Description (last modified by matt)

Goal: allow tracking of unique visitors across device, via the use of a User ID.

This ticket is about

  • a new setUserId() javascript tracking function
  • rename the parameter &cid= to &uid= to be consistent with Google Analytics standard (Keep BC cid->uid).

User ID

Typically, the user ID can be a hash of the user email (if user is logged in), or the hash of the user username.

  • We should provide a hash function in piwik.js as well, to generate the 16char hex string
    • left-pad the input string if needed
  • This feature could be enabled by default, but possible to disable. A new config option:
    enable_javascript_user_id = 1
  • QA: Test that, setting a new User ID will not create a new visit.

Docs & FAQ:

Change History (21)

comment:1 Changed 16 months ago by mmmbee

Or instead, can we just set a custom request in the JavaScript?

For example:

    visitor_id: 'your id',
    additional_data: { /*......*/ }

In this case, we can capture as many parameters in the plugins as we can.

comment:2 Changed 11 months ago by matt (mattab)

  • Milestone changed from 1.12 - The Great 1.x Backlog to 2.x - Piwik 2.x

comment:3 Changed 9 months ago by matt (mattab)

  • Cc tsteur added
  • Description modified (diff)
  • Milestone changed from 2.x - Piwik 2.x to 2.0 - Piwik 2.0
  • Priority changed from normal to major
  • Summary changed from Javascript API allow to setVisitorId to use any ID to define a Visitor to Accurate User Detection cross devices: User ID (set in JS and all other clients)

Cheers @tsteur for the ping

comment:4 Changed 8 months ago by matt (mattab)

from #3089 use case

Other related use case (from email thread)

How to track the source of the visit of a contact form ?

Tracking how many sales from internet is OK, but for medium to big sites would also want to know which Referrer helped the user find our site. Piwik could be used to add the visit information in the emails sent on the site using piwik!

  • The contact form could contain the URL Referrer (stored in piwik cookie) for the visitor, to show what source brought the contact to the site.
  • The email could even show for each visitor, the path used on the site, for each email sent via the contact form... this is possible using the Live API for the visitor ID fetched in JS.


  • in javascript, get the visitorId and possibly the Referrer info (current visit or from ref cookie).
  • Pass the info to the form (eg. Contact form plugin, and/or gravity forms).
  • During the email send, hook and call Piwik API to get info for this visitor.
  • Enhance email text with the piwik info (possibly even have HTML version with flag/techicons ;-)
  • I think we'll have to do most of the work on the piwik side, and provide a new API that gives out just the minimum info needed and would provide a simple aggregate. ->Currently getLastVisits which currently returns all past visits, but could return the referrer info from the most recent and/or first visit, instead of forcing users to loop through and get the ref.
  • Provide simple code example in a blog post or new official doc page ?

How to use Piwik to get this data:

API URL eg.;referrerType==direct&token_auth=X

This was my visitorId fetched by typing: piwikTracker.getVisitorId(); in firebug/javascript console.

Doing this Email enrichment with Piwik is better than other tools which output the referrer or basic user info, since we get access to full APIs, we can know more relevant info about the visit (and display in the email the actual referrer would brought the visitor even if it was few weeks ago :-) )

see also

Last edited 8 months ago by matt (previous) (diff)

comment:5 Changed 7 months ago by matt (mattab)

  • Priority changed from major to normal

comment:6 Changed 7 months ago by matt (mattab)

  • Priority changed from normal to major

comment:7 Changed 7 months ago by matt (mattab)

Also we should note that "Unique Visitors" means in reality "Unique Devices" and maybe this could be mentionned in Column documentation + User docs.

See forum post,107567,page=1#msg-107658

Last edited 5 months ago by matt (previous) (diff)

comment:8 Changed 5 months ago by matt (mattab)

  • Milestone changed from 2.0 - Piwik 2.0 to 2.1 - Piwik 2.1

comment:9 Changed 5 months ago by hpvd

I'm not sure about the way how to do it best.
Should we really set/change the visitor ID for cross device detection if the user "gets a name" (e.g. by logging in)?

Maybe another way is to generated a new additional "User-ID" to which we could add all Visitor IDs.

so we have a structure like that:


  • Visitor-ID (the same user on his desktop @ home)
  • Visitor-ID (the same user on his desktop @ work)
  • Visitor-ID (the same user on his tablet)
  • Visitor-ID (the same user on his smart phone)
  • ...

Doing it that way we could keep all details of "who is who" within piwik and the plugins of forums, shops etc (see ticket only have to submit on each login to piwik the pear of visitor ID and the account/mail/name.

Last edited 5 months ago by hpvd (previous) (diff)

comment:10 Changed 5 months ago by hpvd

and another thing we should take care for:

  • what happens if you track a user within one piwik installation on two different websites where each have a login (identify) possibility where the user uses different user names?
  • what happen if the user visit several websites with login which uses all piwik...

comment:11 Changed 4 months ago by lesjokolat

this is an almost impossible task. one would have to be truly accurate need to implement a method like comscores total universe reporting. whereby an individual is given a panel box and required to each time they logon verify id then users behaviour is assigned to that profile.

in assigning a user id to a machine one can lose site of what happens if one user logs in then someone else starts to use the machine?

the simplest solution though not 100% accurate is like in a paywell environment. a user is given a login and password. one can then assign a unique string then cross refrence it against device type or user agennt.

again limitation is user needs to login. you will have your site of those logged in vs non logged in. hope the sample ratio is enough to give you desired metrics to make informed decisions. one other thing there can also be a privacy issue when one starts to collect user data.(see googles new ad impression user data collection privacy policies)

i see the goal mentioned above but i have to ask what does this goal accomplish? what is the end result desired with the data mined from this? i think determining what this data will provide from an insights perspective should help direct this ticket.

comment:12 Changed 3 months ago by matt (mattab)

See also #2211 piwik.js: Cross domain tracking

comment:13 Changed 2 months ago by matt (mattab)

  • Milestone changed from 2.1 - Piwik 2.1 to 2.0.4 - Piwik 2.0.4

By default Piwik will still work as it has.

So this feature will be used only by some people. When the user is logged in on the site or app, and the webmaster knows an attribute for this particular user that they can use as "unique identifier" for them. for example could use username, uuid, email address, etc.

This will bring much more accuracy to unique users detection and tracking over time. This is simple idea, yet a powerful feature!

Sometimes called Unique User tracking, Unique devices tracking.

comment:14 Changed 2 months ago by matt (mattab)

comment:15 Changed 2 months ago by matt (mattab)

  • Milestone changed from 2.1 - Piwik 2.1 to 2.2 - Piwik 2.2

Entering 2.1 RC cycle, moving all other tickets to 2.2 milestone!

comment:16 Changed 2 months ago by matt (mattab)

  • Description modified (diff)

comment:17 Changed 5 weeks ago by matt (mattab)

  • Milestone changed from 2.2 - Piwik 2.2 to 2.1.1 - Piwik 2.1.1

comment:18 Changed 3 weeks ago by matt (mattab)

  • Owner matt deleted

comment:19 Changed 11 days ago by matt (mattab)

  • Milestone changed from 2.2.1 - Piwik 2.2.1 to 2.x - The Great Piwik 2.x Backlog

comment:20 Changed 10 days ago by matt (mattab)

  • Priority changed from major to critical

comment:21 Changed 23 hours ago by matt (mattab)

Test this code,113975 and check it works fine.

Note: See TracTickets for help on using tickets.