Track user sessions from RudderStack web and mobile sources.
9 minute read
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 ecommerce transactions.
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:
You can expect the following properties in your event’s context object object when session tracking is enabled:
sessionId (Number): The session ID. For more information on how RudderStack calculates sessionId, see FAQ.
sessionStart (Boolean): Present in the first event, indicating the start of the session.
It is strongly recommended to send any other session-related information in the event’s traits or properties as RudderStack’s automatic session tracking overrides any sessionId set in the event’s context object.
Automatic session tracking
By default, the RudderStack SDKs (JavaScript, Android, iOS, React Native, and Flutter) 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.
The server-side SDKs do not support automatic session tracking.
RudderStack also lets you start and end user sessions manually. Refer to the Manual session tracking guide for more information. Note that manual session tracking overrides the automatic session tracking.
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:
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:
rudderanalytics.load(WRITE_KEY,DATA_PLANE_URL,{sessions:{autoTrack:true,timeout:10*60*1000,// 10 min in milliseconds
},...<otherLoadOptions>});
For more information on how session tracking works in the JavaScript SDK, refer to the Session tracking flow section below.
When does a session reset?
The JavaScript SDK resets and starts a new session in the following cases:
When RudderStack receives a new event after the session inactivity period has elapsed, as explained above.
If you identify a user with a new userId in an existing session. RudderStack triggers a reset() call that ends the existing session and generates a new one with a different sessionId.
Get 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:
rudderanalytics.getSessionId();
Mobile SDKs
Note that:
To automatically track sessions in the Android and iOS SDK, withTrackLifecycleEvents should also be set to true.
For the React Native SDK, trackAppLifecycleEvents should be set to true.
By default, automatic session tracking is enabled in the Android SDK:
valrudderClient=RudderClient.getInstance(this,WRITE_KEY,RudderConfig.Builder().withDataPlaneUrl(DATA_PLANE_URL)// Set to false to disable automatic session tracking
.withAutoSessionTracking(true).withSessionTimeoutMillis(5*60*1000).build())
RudderClientrudderClient=RudderClient.getInstance(this,WRITE_KEY,newRudderConfig.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.
Get session ID for Android SDK
The Android 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.
The getsessionId() method is available in the Android SDK from v1.19.0 onwards.
RudderClient.getInstance()?.sessionId
iOS
By default, automatic session tracking is enabled in the iOS SDK:
RSConfigBuilder*builder=[[RSConfigBuilderalloc]init];[builderwithDataPlaneUrl:DATA_PLANE_URL];[builderwithAutoSessionTracking:YES];// Set to No to disable automatic session tracking
[builderwithSessionTimeoutMillis:(5*60*1000)];[RSClientgetInstance:WRITE_KEYconfig:[builderbuild]];
letbuilder: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.
Get session ID for iOS SDK v1
The iOS SDK v1 provides an instance variable sessionId to fetch the current session ID. In case the session ID is unavailable, it returns a null value.
The sessionId instance variable is available in the iOS SDK v1 from v1.20.0 onwards.
[RSClientsharedInstance].sessionId// OR
[[RSClientsharedInstance]sessionId]
RSClient.sharedInstance()?.sessionId
iOS SDK v2
By default, automatic session tracking is enabled in the iOS SDK v2:
To disable automatic session tracking, set autoSessionTracking to false.
Unlike iOS SDK v1, the SDK v2 does not support fetching the current session ID as of now. This feature is coming soon.
Flutter SDK
By default, automatic session tracking is enabled in the Flutter SDK:
finalRudderControllerrudderClient=RudderController.instance;WebConfigwc=WebConfig(autoSessionTracking:true,sessionTimeoutInMillis:10*60*1000);// setting the session timeout to 10 mins
RudderConfigBuilderbuilder=RudderConfigBuilder();builder..withDataPlaneUrl("DATA_PLANE_URL")..withWebConfig(wc);rudderClient.initialize("WRITE_KEY",config:builder.build());
finalRudderControllerrudderClient=RudderController.instance;MobileConfigmc=MobileConfig(autoSessionTracking:true,sessionTimeoutInMillis:3*60*1000);// setting the session time out to 3 mins
RudderConfigBuilderbuilder=RudderConfigBuilder();builder..withDataPlaneUrl("DATA_PLANE_URL")..withMobileConfig(mc)rudderClient.initialize("WRITE_KEY",config:builder.build());
To disable automatic session tracking, set autoSessionTracking to false.
Get session ID for Flutter SDK
The Flutter 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.
int?sessionId=awaitrudderClient.getSessionId();
React Native
By default, automatic session tracking is enabled in the React Native SDK:
construdderInitialise=async()=>{awaitrudderClient.setup(WRITE_KEY,{dataPlaneUrl: DATA_PLANE_URL,trackAppLifecycleEvents: true,autoSessionTracking: true,// Set to false to disable automatic session tracking
sessionTimeout: 5*60*1000,});};rudderInitialise().catch(console.error);
To disable automatic session tracking, set autoSessionTracking to false.
Get session ID for React Native SDK
The React Native SDK provides a getSessionId method to fetch the current session’s ID. If the session ID is unavailable, this method returns a null value.
A sample snippet to fetch the session ID using the React Native SDK:
constsessionId=awaitrudderClient.getSessionId();
Session expiration in mobile SDKs
By default, a session is active until 5 minutes of inactivity have elapsed. For Flutter SDK, this limit is 5 minutes for mobile platforms and 30 minutes for web platforms.
However, you can adjust this limit using the following load option in the respective SDKs:
Load option
RudderStack SDK
Default value
sessionTimeoutMillis
Android and iOS
5 minutes
sessionTimeout
iOS v2 and React Native
5 minutes
sessionTimeoutInMillis
Flutter
5 minutes (mobile platforms)
30 minutes (web platforms)
If the duration between the last received event and the next Application Opened event is more than the session timeout, RudderStack automatically starts a new session. Otherwise, it continues the previous session.
Calling the reset method clears the current sessionId and generates a new one.
For more information on how session tracking works in the mobile SDKs, refer to the Session tracking flow section below.
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:
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.
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.
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.
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:
The SDK then generates a sessionId. For more information on how RudderStack calculates sessionId, refer to the FAQ guide.
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. For more information, refer to the Session expiration in the mobile SDKs section above.
The following diagram summarizes the workflow:
Supported downstream tools
The RudderStack SDKs support sending the sessionId and sessionStart fields to all cloud and warehouse destinations, within the event’s context.
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.
RudderStack maps sessionId to specific fields only in case of the following two destinations:
This site uses cookies to improve your experience while you navigate through the website. Out of
these
cookies, the cookies that are categorized as necessary are stored on your browser as they are as
essential
for the working of basic functionalities of the website. We also use third-party cookies that
help
us
analyze and understand how you use this website. These cookies will be stored in your browser
only
with
your
consent. You also have the option to opt-out of these cookies. But opting out of some of these
cookies
may
have an effect on your browsing experience.
Necessary
Always Enabled
Necessary cookies are absolutely essential for the website to function properly. This
category only includes cookies that ensures basic functionalities and security
features of the website. These cookies do not store any personal information.
This site uses cookies to improve your experience. If you want to
learn more about cookies and why we use them, visit our cookie
policy. We'll assume you're ok with this, but you can opt-out if you wish Cookie Settings.