How does Matomo detect unique and returning visitors? (with User ID or Visitor ID from tracking cookie)

This FAQ explains how the Matomo Tracking API detects unique visitors, and returning visitors, depending on how the Tracking API is used.

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

How does Matomo detect whether the visitor is known?

• If a User ID is set, we will look first for visits where the log_visit.idvisitor matches the Visitor ID (as found in first party tracking cookies). If no visit is matched, we look for visits where either the log_visit.user_id matches the User ID, or where log_visit.config_id matches the visitor config_id. (See Database schema for explanation on log_visit)
• 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 config_id.
• 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 config_id.

When matching visits by visitor/user ID, Matomo looks through the entire history of visits that are currently in the database. When matching visits by device config_id (log_visit.config_id), we only look back window_look_back_for_visitor seconds. By default, this value is set to 30 minutes. This setting can be changed: learn more.

If a visitor is found, then Matomo 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 Matomo considers a visit)

How does Matomo detect a returning visitor?

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

• they have visited the website at least once before this visit and both visits were made using the same browser and with tracking cookies enabled (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 they have visited the website but with tracking cookies deleted or lost, Matomo still managed to find a previous visit from this person (applicable when customising window_look_back_for_visitor to a higher value learn more)
• or they have 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 are visitors tracked across multiple domain names?

By default, Matomo does not track unique visitors across domain names. But if you track multiple domain names in the same website in Matomo, and you want to track your visitors accurately across all the domains, you can use Cross Domain linking for this: learn more in our Measuring Visitors Across Domains – Cross domain linking FAQ.