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 thelog_visit.user_id
matches the User ID, or wherelog_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 forcid
), we only look for visits wherelog_visit.idvisitor
matches this&cid
. - When
trust_visitors_cookies
is set to 1 (see: FAQ abouttrust_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 wherelog_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 thelog_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 thelog_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.