A session is the period of time a user has your app in the foreground or has your website open. For mobile, a session will begin when the app is brought into the foreground and a session will end when the app goes into the background and no events are fired for more than 5 minutes. Events that are sent within 5 minutes of each other are counted towards the current session.
On a browser, a session begins when the website is opened (when the SDK is initialized) and the last event triggered marks the end time of a session. The session timeout on web is 30 minutes.
Important Note:
- Must have the most updated Amplitude JS SDK (version 4.7 or higher) implemented.
- The Amplitude JS SDK must be placed above the Optimizely snippet.
The Session ID is the start time of the session in milliseconds since epoch (Unix Timestamp). All events within the same session will share the same Session ID. If you are using our SDKs, then sessions are tracked automatically. If you are sending Amplitude using our HTTP API, then you will have to explicitly set the Session ID field to track sessions.
Table of Contents
How Sessions Are Tracked
Session ID
The default setting for the Session Property is 'Session ID' property. There is a possibility to change this, please see Custom Session Property. 'Session ID' is the start time of the session in milliseconds since epoch (Unix Timestamp). All events with the same Session ID that are sent by a certain user are in the same session. The Session ID does not need to be unique across multiple users.
Events sent via our SDKs will automatically generate and manage the Session ID. However, by default, the Session ID of events sent via our HTTP API will be -1. A Session ID of -1 means that the event is excluded from all session metrics. Events within a session will be connected with a blue line.
Custom Session Property
Important Note:
- Currently the Custom Session Property is only supported in the User Sessions, Pathfinder and Pathfinder Users chart.
By default, Amplitude sorts events into sessions according to session_id. With our Custom Session Property feature, you can choose to group sessions by an event or user property instead.
This change can be easily switched on/off on your project settings page.
If you want to mark an event as out-of-session, then you can do this by not setting a value for your custom session property for that event. Events without a value for your custom session property will not be included in the User Sessions or Pathfinder charts.
'[Amplitude] Start/End Session' Events
As of August 2015, we no longer by default track the '[Amplitude] Start Session' and '[Amplitude] End Session' events. We use Session ID to track sessions instead of sending start/end session events so that they do not contribute to your monthly event count. If you would like to send event properties for session events, then we recommend tracking your own 'Open App' and 'Close App' events so that you can send event properties with them (e.g. source of the app opening).
If 'Start/End Session' events are critical to your analyses, you can easily turn them on by including the following line before initializing the SDK.
For Android:
Amplitude.getInstance().trackSessionEvents(true);
For iOS:
[Amplitude instance].trackingSessionEvents = true;
Out-of-Session Events
You can also log events as out-of-session by setting the Session ID to -1. Out-of-session events are not considered part of the current session, meaning they do not extend the current session. This might be useful if you are logging events triggered by push notifications. Out-of-session events are normally server-side events sent to Amplitude. See our HTTP API article for information. Out-of-session events will be visualized in a user's event stream with disconnected green squares.
Session Length
Session length is calculated by the following formula (when Session ID is used as Session Property):
max(client_event_time) - session_id
Session length is calculated by the following formula (when Custom Session ID is used as Session Property):
max(client_event_time) - min(client_event_time)
client_event_time: Local timestamp (UTC) of when the device logged the event.
max(client_event_time): The local timestamp (UTC) of the last event logged by the device.
session_id: Local timestamp (UTC) of the start of the session.
Important Note:
- All timestamps are converted into the number of milliseconds since epoch
Timeout Windows
Mobile Sessions
When the SDK is initialized, it determines whether the app is launched into the foreground or background. By default, the timeout window is set to 5 minutes, so if the app is launched in the foreground or if it has been in the background for greater than 5 minutes without firing an event, a new session is created. Events triggered within the timeout window of each other are merged into a single session, and the timeout window can be customized via the SDK. You can read more about tracking sessions through our iOS SDK here and through our Android SDK here.
Browser Sessions
By default, the timeout window is set to 30 minutes. As a result, when the SDK is initialized on the browser, a new session will be created after 30 minutes of inactivity. Events triggered within the timeout window of each other are merged into a single session, and the timeout window can be customized via the JavaScript SDK configuration options.