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.
How sessions are recorded
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.
What causes the splitting of sessions?
There are a few scenarios that could cause a session to split:
30 minutes of visitor inactivity
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.
The user ID changes
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.
The campaign changes
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
The referrer changes (optional)
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
You manually force the start of a new session (optional)
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.
Session limits are exceeded (optional)
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.
How are sessions that span midnight counted?
Sessions that span midnight are counted for both the starting and ending days. This applies to days, weeks and months.
We don’t end sessions at midnight.
Because of this, you might notice variations in session counts across different time frames. For example, if you’re analyzing data day by day, you might see two sessions each day. But if one session stretches past midnight, it’s not counted again, making it appear as three sessions in a report that views the period as a whole.
Just remember, there is a limit on session duration. Sessions exceeding 12 hours, or a set custom limit, will automatically close or restart. To adjust this limit, go to Administration > Sites & apps > Data collection > Session limits or Administration > Settings > Global site & app settings > Data collection > Session limits.
Session limits
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.
Session limits can be changed in: Administration > Sites & apps > Data collection > Session limits or Administration > Settings > Global site & app settings > Data collection > Session limits.
Session and visitor identifiers
Piwik PRO uses the following methods to identify visitors and their sessions:
Cookie ID (JavaScript tracker)
Our JavaScript tracker creates a randomly generated identifier for a visitor called a 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.
The _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 Cookie ID.
Web API: The Cookie ID in the tracking request is passed as the &_id= parameter.
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.
Cookie ID (SDKs)
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 Visitor ID.
A 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.
The 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 &_id= parameter.
Session hash
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 hashVisitor ID. The tracker uses this link to identify events that belong to the same session.
The link between the Session and the hashVisitor 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.hash
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
A 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.
The 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 &uid= parameter.
Visitor ID
A Visitor ID can be based on either a Cookie ID or a User ID.
Usually, the 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 Visitor ID.
If a 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.
If no Cookie ID or User ID exists, the backend tracker will create a random Visitor ID.
The 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.