# Automatic Session Tracking in Mobile SDKs


This guide explains the automatic session tracking feature available in the supported mobile SDKs ([Android (Java)]({{< ref "sources/event-streams/sdks/rudderstack-android-sdk/_index.md" >}}), [iOS (Obj-C)]({{< ref "sources/event-streams/sdks/rudderstack-ios-sdk/_index.md" >}}), [React Native]({{< ref "sources/event-streams/sdks/rudderstack-react-native-sdk.md" >}}), and [Flutter]({{< ref "sources/event-streams/sdks/rudderstack-flutter-sdk/_index.md" >}})).

## Overview

The mobile SDKs support automatic session tracking with the following capabilities:

- All mobile SDKs (Android (Java), iOS (Obj-C), React Native, and Flutter) enable automatic session tracking by default. They consider the [Application Opened]({{< ref "event-spec/standard-events/application-lifecycle-events-spec.md#application-opened" >}}), [Application Installed]({{< ref "event-spec/standard-events/application-lifecycle-events-spec.md#application-installed" >}}), or [Application Updated]({{< ref "event-spec/standard-events/application-lifecycle-events-spec.md#application-updated" >}}) events as the start of a new session.
- By default, each session remains active for 5 minutes of inactivity (30 minutes for Flutter web platforms). See [Session expiration in mobile SDKs](#session-expiration-in-mobile-sdks) for more information.
- The SDKs generate a unique `sessionId` for each session. They also provide a method to retrieve the current session ID.

{{< info >}}
This session ID does not reset when an anonymous user is identified with a new `userId`.
{{< /info >}}

- The SDKs **automatically reset** sessions in the following scenarios:

  - After the specified [inactivity period](#session-expiration-in-mobile-sdks)
  - When you call the `reset()` API
  - When you identify a user with a new `userId` (**except** for anonymous users, where the `reset()` API is not called and the existing session is preserved)

{{< warning >}}
To automatically track user sessions:

- `withTrackLifecycleEvents` should also be set to true in the Android (Java) and iOS SDKs.
- `trackAppLifecycleEvents` should be set to true in the React Native SDK.
{{< /warning >}}

See the [Session tracking flow](#session-tracking-flow) section for a visual workflow of automatic session tracking in the mobile SDKs.

## Manage automatic session tracking

By default, the supported mobile SDKs automatically track user sessions. This section explains how to manage automatic session tracking in the different SDKs.

{{< tabs tabTotal="4">}}
{{% tab tabName="Android (Java) — Legacy" %}}

The following snippet highlights the use of the `withAutoSessionTracking` load option to enable automatic session tracking in the Android (Java) SDK:

```kotlin
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()
    )
```
The corresponding Java code is as follows:

```java
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()
);
```

You can disable automatic session tracking by setting `withAutoSessionTracking` to `false`.
{{% /tab %}}
{{% tab tabName="iOS (Obj-C) — Legacy" %}}
The following snippet highlights the use of the `withAutoSessionTracking` load option to enable automatic session tracking in the iOS (Obj-C) SDK:

```objectivec
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]];
```

The corresponding Swift code is as follows:

```swift
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())
```

You can disable automatic session tracking by setting `withAutoSessionTracking` to `false`.
{{% /tab %}}
{{% tab tabName="iOS SDK v2" %}}
The following snippet highlights the use of the `autoSessionTracking` load option to enable automatic session tracking in the iOS SDK v2:

```objectivec
RSConfig *config = [[RSConfig alloc] initWithWriteKey:WRITE_KEY];
[config dataPlaneURL:DATA_PLANE_URL];
[config autoSessionTracking:YES];
[config sessionTimeout:5*60*1000L];
RSClient *client = [RSClient sharedInstance];
[client configureWith:config];
```

The corresponding Swift code is as follows:

```swift
let config: RSConfig = RSConfig(writeKey: WRITE_KEY)
            .dataPlaneURL(DATA_PLANE_URL)
            .autoSessionTracking(true)
            .sessionTimeout(5*60*1000)
RSClient.sharedInstance().configure(with: config)
```

You can disable automatic session tracking by setting `autoSessionTracking` to `false`.
{{% /tab %}}
{{% tab tabName="React Native" %}}
The following snippet highlights the use of the `autoSessionTracking` load option to enable automatic session tracking in the React Native SDK:

```typescript
const rudderInitialise = async () => {
  await rudderClient.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);
```

You can disable automatic session tracking by setting `autoSessionTracking` to `false`.
{{% /tab %}}
{{% tab tabName="Flutter" %}}
The following snippet highlights the use of the `autoSessionTracking` load option to enable automatic session for **web platforms**:

```dart
final RudderController rudderClient = RudderController.instance;
WebConfig wc = WebConfig(autoSessionTracking: true, sessionTimeoutInMillis: 10 * 60 * 1000); // setting the session timeout to 10 mins
RudderConfigBuilder builder = RudderConfigBuilder();
builder
   ..withDataPlaneUrl("DATA_PLANE_URL")
   ..withWebConfig(wc);
rudderClient.initialize("WRITE_KEY", config: builder.build());
```

The following snippet highlights the use of the `autoSessionTracking` load option to enable automatic session for **mobile platforms**:

```dart
final RudderController rudderClient = RudderController.instance;
MobileConfig mc = MobileConfig(autoSessionTracking: true, sessionTimeoutInMillis: 3 * 60 * 1000); // setting the session time out to 3 mins
RudderConfigBuilder builder = RudderConfigBuilder();
builder
   ..withDataPlaneUrl("DATA_PLANE_URL")
   ..withMobileConfig(mc)
rudderClient.initialize("WRITE_KEY", config: builder.build());
```

You can disable automatic session tracking by setting `autoSessionTracking` to `false`.
{{% /tab %}}
{{< /tabs >}}

## Retrieve the session ID

This section explains how to retrieve the current session ID in the different mobile SDKs.

{{< tabs tabTotal="4">}}
{{% tab tabName="Android (Java) — Legacy" %}}
The {{< legacy-tooltip "android-java" >}} provides a `getSessionId` method to fetch the current session's `sessionId`. In case the session ID is unavailable, this method returns a `null` value.

{{< info >}}
The `getsessionId()` method is available in the Android (Java) SDK from v1.19.0 onwards.
{{< /info >}}

The following snippet highlights the use of the `getSessionId` method:

```kotlin
RudderClient.getInstance()?.sessionId
```

{{% /tab %}}
{{% tab tabName="iOS (Obj-C) — Legacy" %}}
The iOS (Obj-C) SDK provides an instance variable `sessionId` to fetch the current session ID. In case the session ID is unavailable, it returns a `null` value.

{{< info >}}
The `sessionId` instance variable is available in the iOS (Obj-C) SDK from v1.20.0 onwards.
{{< /info >}}

The following snippet highlights the use of the `sessionId` instance variable:

```objectivec
[RSClient sharedInstance].sessionId

// OR

[[RSClient sharedInstance] sessionId]
```

The corresponding Swift code is as follows:

```swift
RSClient.sharedInstance()?.sessionId
```
{{% /tab %}}
{{% tab tabName="iOS SDK v2" %}}
Unlike iOS (Obj-C) SDK, the iOS SDK v2 **does not support** fetching the current session ID.
{{% /tab %}}
{{% tab tabName="React Native" %}}
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.

The following snippet highlights the use of the `getSessionId` method:

```typescript
const sessionId = await rudderClient.getSessionId();
```
{{% /tab %}}
{{% tab tabName="Flutter" %}}
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.

The following snippet highlights the use of the `getSessionId` method:

```dart
int? sessionId = await rudderClient.getSessionId();
```
{{% /tab %}}
{{< /tabs >}}

## 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 (Java) and iOS (Obj-C) | 5 minutes | 
| `sessionTimeout` | iOS SDK v2 and React Native| 5 minutes | 
| `sessionTimeoutInMillis`| Flutter | <ul><li>5 minutes (mobile platforms)</li><li>30 minutes (web platforms)</li></ul> |

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`]({{< ref "event-spec/standard-events/_index.md" >}}) method clears the current `sessionId` and generates a new one.

## Session tracking flow

The automatic session tracking flow (when enabled) in the mobile SDKs is as follows:

1. RudderStack starts the session once it receives the [`Application Opened`]({{< ref "event-spec/standard-events/application-lifecycle-events-spec.md#application-opened" >}}), [`Application Installed`]({{< ref "event-spec/standard-events/application-lifecycle-events-spec.md#application-installed" >}}), or [`Application Updated`]({{< ref "event-spec/standard-events/application-lifecycle-events-spec.md#application-updated" >}}) event.
2. The SDK then generates a `sessionId`.

{{< info >}}
See the [Session Tracking FAQ]({{< ref "sources/event-streams/sdks/session-tracking/faq.md#how-does-rudderstack-determine-the-session-id" >}}) guide for more information on how RudderStack calculates `sessionId`.
{{< /info >}}

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. See [Session expiration in mobile SDKs](#session-expiration-in-mobile-sdks) for more information.

{{< image src="images/event-stream-sources/session-tracking-mobile.webp" alt="Session tracking in mobile SDKs" >}}

## FAQ

See the [Session Tracking FAQ]({{< ref "sources/event-streams/sdks/session-tracking/faq.md#mobile-sdks" >}}) guide for answers to some commonly-asked questions on session tracking in the mobile SDKs.

<br />