In Amplitude, sessions are a useful metric for understanding the frequency and duration of your users' engagement with your product. The most direct way to build a session-based analysis is with the User Sessions chart; however, you can incorporate sessions into other types of analyses through user and event properties.
This article will explain how Amplitude defines and tracks user sessions. By the time you're finished, you should have a solid understanding of how best to incorporate sessions into your Amplitude analyses.
How Amplitude defines "sessions"
Generally, a session is the period of time a user has your app in the foreground or has your website open. The specifics differ slightly between mobile and web applications:
- For mobile, a session begins when the app is brought into the foreground; it ends when the app goes into the background and no events are fired for at least five minutes. All events sent within five minutes of each other are counted towards the current session. Note that you can define your own session expiration time by calling setMinTimeBetweenSessionsMillis(timeout) , where the timeout input is in milliseconds.
- On a browser, a session begins when the website is opened and the SDK is initialized; it ends when the last event is triggered. Web sessions time out after 30 minutes by default. All events fired within 30 minutes of each other are counted as part of the same session. This timeout window can be customized via the JavaScript SDK configuration options.
Amplitude automatically generates a session ID for each new session; that ID is the session's start time in milliseconds since epoch (also known as the Unix timestamp). All events within the same session share the same session ID. If you are using Amplitude's SDKs, this happens automatically. However, if you are sending data to Amplitude using the HTTP API, you will have to explicitly set the session ID field in order to track sessions.
How Amplitude tracks your sessions
By default, the setting in Amplitude for the session property is session ID. All events with the same session ID and the same user ID will be grouped into the same session. The session ID does not have to be unique across multiple users.
NOTE: This setting can be changed; please see the custom session property section for more information.
As noted above, session IDs for events sent via the Amplitude SDKs are automatically generated and managed. However, for events sent via the HTTP API, Amplitude defaults to a session ID of -1. This means the event is excluded from all session metrics.
NOTE: This commonly occurs when sending data to Amplitude from Segment via a cloud-mode connection. As with sending data via HTTP API, you will have to explicitly set a session ID to track sessions.
Events included in the same session will be connected with a blue line, as shown above.
Start Session and End Session events
Amplitude does not track Start Session and End Session events by default, but it can still determine the beginning and ending times of sessions by tracking session IDs. Amplitude also uses session ID to calculate session lengths. This way, these events do not contribute to your monthly event count.
That said, if trackingStart Session andEnd Session events is critical to your analysis outside of session lengths, you can easily turn on tracking for these events by adding this line of code before initializing the SDK:
For Android:
Amplitude.getInstance().trackSessionEvents(true);
For iOS:
[Amplitude instance].trackingSessionEvents = true;
Important Notes:
- This only applies to Amplitude's Android and iOS SDKs. The JavaScript SDK cannot send default session events.
- Start/End Session events count towards your monthly event volume limit.
- The
End Sessionevent will be sent at the start of the user's next session. - You will not be able to add additional event properties to these Start Session and End Session events. If you would like to send event properties for session start/end events, try implementing your own custom
Open AppandClose Appevents.
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. Because they do not extend the current session, they can be useful if you're logging events triggered by push notifications.
Out-of-session events are normally server-side events received by Amplitude (see our HTTP API article for more details). These events will appear in a user's event stream as disconnected green squares.
Custom session property
Important Note:
- This property is only supported in the User Sessions, Pathfinder and Pathfinder Users charts.
By default, Amplitude sorts events into sessions according to session ID. By using a custom session property, you can choose to group sessions by an event or user property instead.
This change can be easily switched on or off from your project settings page.
If you want to mark an event as out-of-session, you can do so by not setting a value for your custom session property for that event. Events without this value will not be included in the User Sessions or Pathfinder charts.
How Amplitude calculates session length
Amplitude calculates session length via the following formula when session ID is used as the session property:
max(client_event_time) - session_id
When custom session ID is used as the session property, Amplitude will use this formula instead:
max(client_event_time) - min(client_event_time)
Where:
client_event_timeis the local timestamp (UTC) when the device logged the eventmax(client_event_time)is the local timestamp (UTC) of the last event logged by the devicesession_idis the local timestamp (UTC) of the start of the session
Additionally, hidden, inactive, and deleted events will not be included in the session length calculation. For example, let's say you have the following series of events:
Event A --> Event B --> Event C --> Event D
If Event C and Event D are hidden, inactive, or deleted in Govern, then the max(client_event_time) is taken from Event B instead of Event D.