A session is a visit to your site or app from a single visitor. It consists of events like page views, downloads, outlinks, custom events, goal conversions, ecommerce conversions and so on. To know that events were performed by the same person in one session, Piwik PRO may use session and visitor identifiers like Cookie ID and Session ID.
In this article, we’ll explain how Piwik PRO processes a session, determines when to start a new session and identifies visitors.
How a session is recorded
When a visitor comes to your site with Piwik PRO installed, 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 like 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 in Analytics, but not included in reports yet. Piwik PRO waits for the visitor’s session to end (which takes 30 minutes after the last event was collected) before aggregating all the events into a report and saving them in the database.
As a backup, Piwik PRO keeps a duplicate of each tracking request. The raw logs are stored for 30 days, and the events are stored for 7 days before they’re permanently deleted.
What causes a session to be split
There are a few scenarios that lead to the splitting of one session:
30 minutes of visitor inactivity
A session begins with the first event and ends 30 minutes after the last event. When Piwik PRO records the last event of a visitor, it waits for 30 minutes before considering their session closed. Any event that occurs after this 30-minute period is counted as a new session.
The 30-minute period of inactivity can’t be changed.
Campaign changes
If the campaign that brought a visitor to your site changes while they are browsing because they click on a link with different campaign parameters, Piwik PRO may start a new session for that visitor. By doing so, Piwik PRO will keep a record of all the campaigns that direct traffic to your site.
This is the default behavior. You can change it using these 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
Referrer changes (optional)
If the site that referred a visitor to your site changes while they are browsing because they click on a link on another referring site, Piwik PRO may start a new session for that visitor. By splitting the session, Piwik PRO will keep track of all referring sites.
This is not the default behavior. It only applies if these settings are 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
Force a new session manually (optional)
While using our web API, you can force a new session manually by including the &new_visit=1 parameter in the tracking request.
Session limits
The 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.
The session that goes over the limit is closed and the next matching events are marked as Excluded events and don’t reach the reporting engine. When a session exceeds these limits, it’s usually due to spam or a bot.
Session and visitor identifiers
Piwik PRO recognizes visitors and their sessions using the following methods:
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 recognize 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 cookie again 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 > Ask visitors for consent (off) > Use visitor cookies (off)), the tracker will only use the Session ID to recognize 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 and then this ID is 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 ID
Our backend tracker creates a hash called a Session ID 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 ID and the Visitor ID. The tracker uses this link to recognize events that belong to the same session.
The link between the Session ID and the Visitor ID expires 30 minutes after the last event. Since we don’t store the Session ID anywhere else, it’s impossible to identify returning visitors based on its value alone.
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 time, 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 time, it’s permanently deleted.
Note: If you turn off Use a session ID (Administration > Sites & Apps > Privacy > Ask visitors for consent (off) > Use a session ID (off)), the tracker will only use the Cookie ID from the cookie to recognize 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 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 ID mechanism, that previous Cookie ID will be considered the final Visitor ID.
If there is a User ID, the Visitor ID will always be based on that User ID, so it will stay the same every time that user visits the site.
If there is no Cookie ID or User ID, the backend tracker will create a random Visitor ID.
The Visitor ID is used to calculate the number of unique visitors and recognize new and returning visitors, but plays no direct role in recognizing the visitor’s session.