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, Matomo 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, Matomo looks for visits where either the log_visit.user_id matches the User ID, or where log_visit.config_id matches the visitor config_id. Read more on the explanation for log_visit.
• When a Visitor ID is manually set in the Tracking API via &cid=, Matomo only looks for visits where log_visit.idvisitor matches this &cid.
• When trust_visitors_cookies is set to 1, and a visitor ID is found either in first party cookie _pk_id or in the third party cookie, Matomo only looks 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, Matomo looks first for visits where the log_visit.idvisitor matches the visitor ID from cookie. If no visit is matched, then Matomo looks 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=, Matomo only looks 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), Matomo only looks back window_look_back_for_visitor seconds. By default, this value is set to 30 minutes and the setting can be changed.

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.