Manual Session Tracking in RudderStack SDKs
5 minute read
This guide explains the manual session tracking feature available in the supported RudderStack SDKs (JavaScript, Android (Java), iOS (Obj-C), React Native, and Flutter).
Overview
You can use the manual session tracking feature to define the start and end of a user session.
Manual session tracking overrides the automatic session tracking.
RudderStack supports the following manual session tracking methods:
| Method | Parameters | Description |
|---|---|---|
startSession() | - | RudderStack creates a new session and passes the current timestamp as the sessionId if you don't pass any parameter. |
sessionIdLong integer with minimum length of 10 characters. | RudderStack triggers a new user session if you pass a custom sessionId parameter.RudderStack does not recommend using a decimal number as the sessionId. | |
endSession() | - | RudderStack clears the sessionId and ends the session. |
Persistence scope
The following sections list the persistence scope of manual session tracking in the JavaScript and mobile SDKs.
JavaScript
The persistence scope of manual session tracking in the JavaScript SDK does not depend on whether automatic session tracking is enabled.
If you call startSession(), the manual session continues even if you refresh or reopen the web page. A manual session has no inactivity timeout. It lasts until you call endSession() or reset(), or the SDK storage is cleared.
If you identify a user with a newuserIdin an existing session, RudderStack triggers areset()call. This ends the existing session and generates a new one, irrespective of whetherendSession()is called or not.
In the JavaScript SDK, startSession(sessionId) requires a positive integer with at least 10 digits. If you pass any other value, the SDK logs a warning and uses an auto-generated session ID (the current timestamp in milliseconds) instead.
See Session tracking for the JavaScript SDK API reference.
Start the session before tracking calls
To include events tracked before the JavaScript SDK loads in a manual session, call startSession() right after load() and before any page or track call:
rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL);
rudderanalytics.startSession();
rudderanalytics.page();The SDK replays calls made before it loads in invocation order, so each event uses the session started before it. Don’t call startSession() in the onLoaded callback — it runs after the buffered calls are replayed, so those events aren’t part of the new session. See Processing order for details.
If you load the SDK through a tag manager, put load() and startSession() in the same tag and make sure that tag fires before your tracking tags.
Mobile SDKs
The persistence scope of manual session tracking in the mobile SDKs (Android (Java), iOS (Obj-C), React Native, and Flutter) depends on whether automatic session tracking is enabled:
- If automatic session tracking is enabled and you call
startSession(), then RudderStack disables automatic session tracking until the app is closed completely. Once you restart the app, the SDKs resume automatic session tracking. - If automatic session tracking is disabled and you call
startSession(), the manual session is active until you end it by callingendSession().
Sample snippets
The following snippets highlight the use of the manual session tracking methods:
rudderanalytics.startSession() // Starts a new user session and automatically assigns a session ID.
rudderanalytics.startSession(sessionId) // Passes a custom session ID while creating a new session.
rudderanalytics.endSession() // Ends the user session and clears the session ID.
The manual session tracking methods in the Android (Java) SDK are available in the following languages:
- Java
- Kotlin
The following snippets highlight the use of the manual session tracking methods:
rudderClient.startSession(); // Starts a new user session and automatically assigns a session ID.
rudderClient.startSession(sessionId); // Passes a custom session ID while creating a new session.
rudderClient.endSession(); // Ends the user session and clears the session ID.The corresponding Kotlin code is as follows:
// Starts a new user session and automatically assigns a session ID.
rudderClient.startSession()
// Passes a custom session ID while creating a new session.
rudderClient.startSession(sessionId)
// Ends the user session and clears the session ID.
rudderClient.endSession()The manual session tracking methods in the iOS (Obj-C) SDK are available in the following languages:
- Swift
- Objective-C
The following snippets highlight the use of the manual session tracking methods:
RSClient.sharedInstance()?.startSession() // Starts a new user session and automatically assigns a session ID.
RSClient.sharedInstance()?.startSession(sessionId) // Passes a custom session ID while creating a new session.
RSClient.sharedInstance()?.endSession() // Ends the user session and clears the session ID.The corresponding Objective-C code is as follows:
[[RSClient sharedInstance] startSession]; // Starts a new user session and automatically assigns a session ID.
[[RSClient sharedInstance] startSession:sessionId]; // Passes a custom session ID while creating a new session.
[[RSClient sharedInstance] endSession]; // Ends the user session and clears the session ID.// Starts a new user session and automatically assigns a session ID.
rudderClient.startSession();
// Passes a custom session ID while creating a new session.
rudderClient.startSession(sessionId);
// Ends the user session and clears the session ID.
rudderClient.endSession();// Starts a new user session and automatically assigns a session ID.
rudderClient.startSession();
// Passes a custom session ID while creating a new session.
rudderClient.startSession(sessionId);
// Ends the user session and clears the session ID.
rudderClient.endSession();FAQ
See the Session Tracking FAQ guide for answers to some commonly-asked questions on session tracking.
