This FAQ explains how does Piwik Tracking API detect unique visitors, and returning visitors, depending on how the Tracking API is used.

When a visitor views a page or screen, Piwik will attempt to detect whether this request belongs to an existing visit, and/or whether the visitor has visited the website before.

How does Piwik detect whether the visitor is known?

  • If a User ID is set, either via setUserId in your favorite SDK or via &uid= in the Tracking API, this User ID will be converted (hashed) into a Visitor ID hexadecimal string. The hashed User ID becomes the Visitor ID. We look first for visits where the log_visit.idvisitor matches this Visitor ID (User ID). If no visit is matched, we look for visits where the log_visit.config_id matches the visitor fingerprint.
  • When a Visitor ID was manually set in the Tracking API via &cid= (see: Tracking API reference for cid), we only look for visits where log_visit.idvisitor matches this &cid.
  • When trust_visitors_cookies is set to 1 (see: FAQ about trust_visitor_cookies), and a visitor ID is found either in first party cookie _pk_id (see: first party tracking cookies) or in the third party cookie (see: enabling third party cookies), we only look for visits where log_visit.idvisitor matches the visitor ID from cookie.
  • Otherwise when a visitor ID is found in a first party cookie or in the third party cookie, we look first for visits where the log_visit.idvisitor matches the visitor ID from cookie. If no visit is matched, we look for visits where the log_visit.config_id matches the visitor fingerprint.
  • Finally, when there is no visitor ID found in first party cookie (nor in the third party cookie) and a visitor ID was not specified via &cid=, we only look for visits where the log_visit.config_id matches the visitor fingerprint.

In all cases, when “looking for visits” in the past, we look back window_look_back_for_visitor seconds. By default, Piwik will look back 30 minutes (default value for window_look_back_for_visitor INI setting). This setting can be changed: learn more.

If a visitor is found, then Piwik will assign the current request to this existing visitor, either by updating the current visitor’s visit or by creating a new visit when appropriate (learn more about what Piwik considers a visit)

How does Piwik detect a returning visitor?

A visitor will be marked as ‘Returning visitor’ when:

  • she has visited the website at least once before this visit (this can be detected via the ‘visit count’ and ‘first visit time’ and ‘last visit time’ found in tracking cookie and sent to Tracking API as &_idvc= and &_idts= and &_viewts=)
  • or she has visited the website but with tracking cookies deleted or lost, Piwik still managed to find a previous visit from this person (applicable when customising window_look_back_for_visitor learn more)
  • or she has purchased an item on the website before this visit (according to the ‘last ecommerce order date’ found in tracking cookie and sent to Tracking API as &_ects=)

How is the visitor fingerprint processed?

The visitor fingerprint is a hash of a set of the visitor’s settings and attributes. The fingerprint (also called config_id or config hash) is a unique string calculated for a visitor based on their operating system, browser, browser plugins, IP address and browser language. This fingerprint is necessary to process unique visitors accurately, but we aim to take all possible measures to protect users privacy:

  • the website ID is used to process the visitor fingerprint hash which means that on your Piwik instance, a given user/visitor will have a different fingerprint hash when browsing your different websites. (this is the default behavior which can be disabled by setting enable_fingerprinting_across_websites to 1)
  • the IP address used to create the hash will be the anonimized IP address when you have enabled IP anonimisation which is the default privacy setting in Piwik (when you select “Also use anonymised IP when enriching visit: No” then the full IP address will be used in the hash calculation).
  • a unique salt is used for each Piwik instance so that a same user/visitor’s hashes are different across several Piwik servers (this cannot be disabled).

Any questions?

Many answers and more information about Piwik You can find here:

We are social

Follow us: