A session is a visit to your site or app by a single visitor. It consists of events like page views, downloads, outlinks, custom events, goal conversions, ecommerce conversions and so on. To identify events performed by the same person in one session, Piwik PRO may use session and visitor identifiers such as cookie IDs and session hashes.
In this article, we’ll explain how Piwik PRO processes sessions, determines when to start a new one and identifies visitors.
When a visitor lands on a site on which you’ve installed Piwik PRO, the tracker sends a tracking request to the Piwik PRO server. The tracking request is buffered, batched and sent to permanent storage as a log.
The processing service picks up the log, enriches it with data such as visitor’s location, device, referrer and so on, and turns it into an event. The event is then buffered, batched and sent to permanent storage.
While in permanent storage, the event is visible in the tracker debugger, but not yet included in reports. Piwik PRO waits for the visitor’s session to end before aggregating all the events into a report and saving them in the database. The session ends 30 minutes after the last event.
As a backup, Piwik PRO keeps a copy of each tracking request. Raw logs are stored for 30 days and events for 7 days before being permanently deleted.
There are a few scenarios that could cause a session to split:
A session begins with a visitor’s first event and ends 30 minutes after their last one. When Piwik PRO records a visitor’s last event, it waits for 30 minutes before considering their session closed. Any event that occurs after this 30-minute period is recorded as a new session.
The 30-minute period of inactivity can’t be changed.
If a user ID changes during a visitor’s session, Piwik PRO will start a new session for that visitor. This mechanism guarantees accurate user and session counts, especially when multiple visitors are using the same device or switching between different accounts by logging in and out.
This mechanism can’t be changed.
If the campaign that brought a visitor to your site changes while they are browsing because they’ve clicked on a link with different campaign parameters, Piwik PRO may start a new session for that visitor. This allows Piwik PRO to keep a separate record of all the campaigns that direct traffic to your site.
This is the default behavior. You can change it using the following settings:
- Administration > Sites & apps > Data collection > Start a new session when the campaign changes
- Administration > Settings > Global site & app settings > Start a new session when the campaign changes
- Web API: create_new_visit_when_campaign_changes
If the site that referred a visitor to your site changes while they are browsing because they’ve clicked on a link on another referring site, Piwik PRO may start a new session for that visitor. This allows Piwik PRO to keep track of all referring sites.
This is not the default behavior. It only applies if one of the following settings is turned on:
- Administration > Sites & apps > Data collection > Start a new session when the referrer changes (on)
- Administration > Settings > Global site & app settings > Start a new session when the referrer changes (on)
- Web API: create_new_visit_when_website_referrer_changes
While using our web API, you can force the start of a new session by including the
&new_visit=1 parameter in your tracking request.
If one of the session limits is exceeded, Piwik PRO may create a new session for the visitor.
This is not the default behavior. It only applies when one of the following settings is set:
- Administration > Sites & apps > Data collection > Session limits > If session limits are exceeded: Create a new session.
- Administration > Global site & app settings > Data collection > Session limits > If session limits are exceeded: Create a new session.
A session has two types of limits:
- No. of events in a session. Default value: 5000. Max limit: –.
- Session duration. Default value: 12 hours. Max limit: 12 hours.
When a session exceeds either of these limits, it is closed, and subsequent matching events are marked as
Excluded events and excluded from the reporting engine. Sessions exceeding their limits are usually caused by spam or bots.
Piwik PRO uses the following methods to identify visitors and their sessions:
Cookie ID. This ID is stored in the
_pk_id cookie, which is set in the visitor’s browser. The tracker uses this ID to identify the visitor and their session.
_pk_id cookie expires after 13 months by default (or after 30 minutes for anonymous visitors if the 30-minute cookie option is turned on). However, if a visitor clears their cookies, the tracker will set a new cookie with a new
Web API: The
Cookie ID in the tracking request is passed as the
Note: If you turn off Use visitor cookies (Administration > Sites & Apps > Privacy > Compliances > Use visitor cookies (off)), the tracker will only use the
Session hash to identify the visitor’s session.
Note: We call it
Cookie ID and that’s how it’s reported in Piwik PRO, but our SDK documentation uses the term
Visitor ID. In fact, the SDK creates a
Cookie ID which is then copied to the
Visitor ID. In reports you’ll always see two values,
Cookie ID and
Cookie ID is a randomly generated identifier that is assigned to the user’s device when the mobile app is installed. For privacy reasons, Piwik PRO doesn’t use the Android or iOS device IDs.
Cookie ID value stays in the app as long as it’s installed.
Web API: The
Cookie ID in the tracking request is stored in the
Our backend tracker creates a hash called a
Session hash for each session based on the visitor’s IP address, operating system, browser name, browser version, browser language, enabled browser plugins and Piwik PRO site/app ID. During tracking, a temporary link is created between the
Session and the
Visitor ID. The tracker uses this link to identify events that belong to the same session.
The link between the
Session and the
Visitor ID expires 30 minutes after the last event. Since we don’t store the
Session anywhere else, it’s impossible to identify visitors solely on the basis of the hash’s value.
The hash itself is not available in any reports, but the data used to create it is visible in raw requests in the tracker debugger for 6 hours. After that, it’s stored in raw log format for 30 days, but is not available in the application interface (We only store it for security reasons: (1) to protect us from malicious actions and bots, (2) to troubleshoot any tracking issues and (3) to recover data in case of data loss.). After that, it’s permanently deleted.
Note: If you turn off Use a session hash (Administration > Sites & Apps > Privacy > Compliances > Use a session hash (off)), the tracker will only use the
Cookie ID from the cookie to identify visitors.
User ID is an additional identifier that can be given to a visitor if you choose to set it up. This identifier can be any unique identifier that you send from your site or app to the tracker. It can be the same identifier that you use in your CMS, CRM or sales system.
User ID overwrites the
Visitor ID in a deterministic way. This means that for each unique
User ID, there will always be the same
Visitor ID. However, the
User ID doesn’t play a direct role in identifying a visitor’s session.
Web API: The
User ID in the tracking request is stored in the
Visitor ID can be based on either a
Cookie ID or a
Visitor ID is the same as the
Cookie ID. If a previous session with a different
Cookie ID is matched using the
Session hash mechanism, that previous
Cookie ID will be considered the final
User ID exists, the
Visitor ID will always be based on it, and will therefore stay the same every time that user visits the site.
Cookie ID or
User ID exists, the backend tracker will create a random
Visitor ID is used to calculate the number of unique visitors and identify new and returning visitors, but plays no direct role in identifying visitors’ sessions.