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.

With the help of RudderStack's session tracking feature, you can gather the event tracking metrics and combine it with the session metadata to better understand the user's product journey and analyze their behavior. You can also use the resulting insights to identify problems and optimization opportunities in your product workflow.

Session tracking in RudderStack SDKs

The following RudderStack SDKs support the session tracking feature:

Automatic session tracking

By default, the RudderStack SDKs (JavaScript, Android, and iOS) 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.

JavaScript SDK

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

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

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

When does a session become inactive?

By default, a session is active until 30 minutes of inactivity have elapsed since the last received event. Whenever RudderStack receives a new event, it checks if the inactivity period has elapsed. If yes, it starts a new session with a new sessionId. Otherwise, it continues the previous session.

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.

You can also adjust the inactivity period using the timeout load option. The following snippet highlights the use of the timeout option to set a custom session timeout of 10 minutes:

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

Mobile SDKs

Android

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

Copy
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()
)

Copy
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:

Copy
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]];

Copy
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 automatically starts a new session. Otherwise, it continues the previous session.

Getting session ID for JavaScript SDK

The JavaScript SDK provides a getSessionId method to fetch the current session's sessionId. In case the session ID is unavailable, this method returns a null value.

A sample snippet to fetch the current session ID is as shown:

Copy
rudderanalytics.getSessionId();

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.

3. The SDK records the user events and the session is active until the timeout (default 30 minutes of inactivity) period has elapsed since the last received event. If yes, it starts a new session with a new sessionId.
4. Otherwise, the SDK updates the session expiration time by adding the last event's timestamp to the timeout period (default 30 minutes).

The following diagram summarizes the workflow:

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.

3. The SDK records the user events and the session is active until more than sessionTimeoutMillis (default 5 minutes) period of inactivity has elapsed since the last received event.

The following diagram summarizes the workflow:

Supported downstream tools

The RudderStack SDKs support sending the sessionId and sessionStart fields to all the cloud and warehouse destinations, within the event's context.

It is important to note the following:

• RudderStack passes the sessionId to all 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.

RudderStack maps sessionId to specific fields only in case of the following two destinations:

FAQ

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