What is a session?

A session is a group of user interactions with your website or mobile app within a given time frame. It is usually triggered when a user opens a mobile app or a website in their browser and ends after a particular period of inactivity.

A single session can contain multiple page views or screen views, events, social interactions, and e-commerce transactions.

Session tracking in RudderStack

You can use RudderStack's session tracking feature to determine the average time users spend on an app and how they engage with it. By combining the session metadata with the usage data like event tracking, you can better understand the user's product journey and analyze their behavior effectively. You can also use the resulting insights to identify problems and optimization opportunities in your product workflow.

The following RudderStack SDKs support the session tracking feature:

RudderStack SDKMinimum supported version
JavaScriptv1 - 1.16.0 (CDN)
v1.1 - 2.15.0 (CDN & NPM)
Androidv1.7.0
iOSv1.7.0

If the session tracking feature is enabled, you can expect the following properties in your event's context object:

  • sessionId (Number): The unique session ID.
  • sessionStart (Boolean): Present in the first event, indicating the start of the session.
The session tracking feature overrides any sessionId set in the event's context object. Hence, it is strongly recommended to send any session-related information in the event's traits or properties.

Automatic session tracking

By default, the above-mentioned RudderStack SDKs automatically track the user sessions. This means that RudderStack automatically determines the start and end of a session depending on the inactivity time configured in the SDK.

RudderStack also lets you start and end user sessions manually. Refer to the Manual session tracking section below for more information.

JavaScript SDK

In case of the JavaScript SDK, RudderStack considers the SDK initialization as the start of a user session.

To disable automatic session tracking, you can set the load option autoTrack to false, as shown:

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
sessions: {
autoTrack: false, // Set to false to disable automatic session tracking
},
...<otherLoadOptions>
});

By default, a session is active until 30 minutes of inactivity have elapsed since the last received event. However, you can adjust this limit using the timeout load option, as shown:

rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL, {
sessions: {
autoTrack: true,
timeout: 10 * 60 * 1000, // 10 min in milliseconds
},
...<otherLoadOptions>
});

Every time a new event is generated (track, page, identify, etc.), the SDK resets the session expiration time by adding the configured timeout (default 30 minutes) to the last received event's timestamp.

For more information on how session tracking works in the JavaScript SDK, refer to the Session tracking flow section below.

Mobile SDKs

To automatically track sessions in the Android and iOS SDK, withTrackLifecycleEvents should also be set to true. This is because RudderStack considers the Application Opened, Application Installed, or Application Updated events as the start of a new session.

Android

By default, automatic session tracking is enabled in the Android SDK, as shown:

val rudderClient = RudderClient.getInstance(
this,
WRITE_KEY,
RudderConfig.Builder()
.withDataPlaneUrl(DATA_PLANE_URL)
.withAutoSessionTracking(true) // Set to false to disable automatic session tracking
.withSessionTimeoutMillis(5*60*1000)
.build()
)
RudderClient rudderClient = RudderClient.getInstance(
this,
WRITE_KEY,
new RudderConfig.Builder()
.withDataPlaneUrl(DATA_PLANE_URL)
.withAutoSessionTracking(true) // Set to false to disable automatic session tracking
.withSessionTimeoutMillis(5*60*1000)
.build()
);

To disable automatic session tracking, set withAutoSessionTracking to false.

iOS

By default, automatic session tracking is enabled in the iOS SDK, as shown:

RSConfigBuilder *builder = [[RSConfigBuilder alloc] init];
[builder withDataPlaneUrl:DATA_PLANE_URL];
[builder withAutoSessionTracking:YES]; // Set to No to disable automatic session tracking
[builder withSessionTimeoutMillis:(5*60*1000)];
[RSClient getInstance:WRITE_KEY config:[builder build]];
let builder: RSConfigBuilder = RSConfigBuilder()
.withDataPlaneUrl(DATA_PLANE_URL)
.withAutoSessionTracking(true) // Set to false to disable automatic session tracking
.withSessionTimeoutMillis(5*60*1000)
RSClient.getInstance(WRITE_KEY, config: builder.build())

To disable automatic session tracking, set withAutoSessionTracking to false.

Session expiration in mobile SDKs

By default, a session is active until 5 minutes of inactivity have elapsed. However, you can adjust this limit using the sessionTimeoutMillis load option, as seen in the above snippets.

If the duration between the last received event and the next Application Opened event is more than sessionTimeoutMillis, RudderStack starts a new session. Otherwise, it continues the previous session.

For more information on how session tracking works in the mobile SDKs, refer to the Session tracking flow section below.

Manual session tracking

This section is applicable for all the supported RudderStack SDKs (JavaScript, Android, and iOS).

RudderStack also supports manual session tracking using the following methods that indicate the start and end of a user session:

MethodParametersDescription
startSession()-RudderStack creates a new session and passes the event's timestamp as the sessionId.
startSession()sessionId (Long integer with minimum length of 10 characters). It is not recommended to use a decimal number.You can pass a custom sessionId and trigger a new user session.
endSession()-RudderStack clears the sessionId and ends the session.
Note that manual session tracking overrides automatic session tracking. If automatic session tracking is enabled and you call the startSession() API, then RudderStack will disable automatic session tracking until the app is closed completely. For more information, refer to the FAQ section.

Session tracking flow

The following sections describe how the session tracking works in the RudderStack SDKs.

JavaScript SDK

If session tracking is enabled in the JavaScript SDK, the flow is as explained below:

  1. During the initialization, the SDK checks for an existing user session. If no valid session exists, it creates a new session. Otherwise, the SDK proceeds with the existing session.
  2. Upon receiving an event, the SDK fetches the sessionId. If no valid sessionId is found, it creates a new session and returns the sessionId.
    • If this is the first event of the session, the SDK also sends another parameter in the context called sessionStart: true.
For more information on how RudderStack calculates sessionId, refer to the FAQ guide.
  1. Finally, the SDK updates the session expiration time, that is, the last event's timestamp + timeout (default 30 minutes).

The following diagram summarizes the workflow:

Session tracking in JavaScript SDK

Mobile SDKs

If session tracking is enabled in the mobile SDKs, the flow is as explained below:

  1. RudderStack starts the session once it receives the Application Opened, Application Installed, or Application Updated event.
  2. The SDK then generates a sessionId.
For more information on how RudderStack calculates sessionId, refer to the FAQ guide.
  1. The SDK records the user events and the session is active until more than sessionTimeoutMillis (default 5 minutes) of inactivity have elapsed since the last received event.
For more information, refer to the Session expiration in the mobile SDKs section above.

The following diagram summarizes the workflow:

Session tracking in mobile SDKs

Supported downstream tools

RudderStack supports forwarding the sessionId and sessionStart fields to the following downstream destinations:

DestinationNotes
AmplitudeReference
Mixpanel
  • RudderStack passes $session_id under the event properties.
  • Mixpanel doesn't have any specific field for $session_id but you can use this field in the reports.

It is important to note the following:

  • RudderStack passes the sessionId to the subsequent events in the context.sessionId field.
  • RudderStack sets the context.sessionStart field to true in the first event to indicate the start of the session.

FAQ

Refer to the Session Tracking FAQ guide for a comprehensive list of questions on session tracking.


Contact us

For more information on the topics covered on this page, email us or start a conversation in our Slack community.

On this page