Track sessions

Learn how to track sessions through the Braze SDK.

About the session lifecycle

A session refers to the period of time the Braze SDK tracks user activity in your app after it’s launched. You can also force a new session by calling the changeUser() method.

• web
• android
• swift

Defining inactivity

Understanding how inactivity is defined and measured is key to managing session lifecycles effectively in the Web SDK. Inactivity refers to a period during which the Braze Web SDK does not detect any tracked events from the user.

How inactivity is measured

The Web SDK tracks inactivity based on SDK-tracked events. The SDK maintains an internal timer that resets each time a tracked event is sent. If no SDK-tracked events occur within the configured timeout period, the session is considered inactive and ends.

For more information on how session lifecycle is implemented in the Web SDK, see the session management source code in the Braze Web SDK GitHub repository.

What counts as activity by default:

• Opening or refreshing the web app
• Interacting with Braze-driven UI elements (such as In-app messages or Content Cards)
• Calling SDK methods that send tracked events (such as custom events or user attribute updates)

What does not count as activity by default:

• Switching to a different browser tab
• Minimizing the browser window
• Browser focus or blur events
• Scrolling or mouse movements on the page

Session timeout configuration

By default, the Web SDK considers a session inactive after 30 minutes without any tracked events. You can customize this threshold when initializing the SDK using the sessionTimeoutInSeconds parameter. For details on configuring this parameter, including code examples, see Changing the default session timeout.

Example: Understanding inactivity scenarios

Consider the following scenario:

1. A user opens your website, and the SDK starts a session by calling braze.openSession().
2. The user switches to a different browser tab to view another website for 30 minutes.
3. During this time, no SDK-tracked events occur on your website.
4. After 30 minutes of inactivity, the session automatically ends.
5. When the user switches back to your website tab and triggers an SDK event (such as viewing a page or interacting with content), a new session begins.

Tracking custom inactivity

If you need to track inactivity based on browser visibility or tab switching, implement custom event listeners in your JavaScript code. Use browser events such as visibilitychange to detect when users leave your page, and manually send custom events to Braze or call braze.openSession() when appropriate.

1
2
3
4
5
6
7
8
9
10
11
// Example: Track when user switches away from tab
document.addEventListener('visibilitychange', function() {
  if (document.hidden) {
    // User switched away - optionally log a custom event
    braze.logCustomEvent('tab_hidden');
  } else {
    // User returned - optionally start a new session and/or log an event
    // braze.openSession();
    braze.logCustomEvent('tab_visible');
  }
});

For more information on logging custom events, refer to Log custom events. For details on session lifecycle and timeout configuration, refer to Changing the default session timeout.

Subscribing to session updates

Step 1: Subscribe to updates

To subscribe to session updates, use the subscribeToSessionUpdates() method.

• web
• android
• swift
• react native

1
2
3
4
5
6
7
8
Braze.getInstance(this).subscribeToSessionUpdates(new IEventSubscriber<SessionStateChangedEvent>() {
  @Override
  public void trigger(SessionStateChangedEvent message) {
    if (message.getEventType() == SessionStateChangedEvent.ChangeType.SESSION_STARTED) {
      // A session has just been started
    }
  }
});

1
2
3
4
5
Braze.getInstance(this).subscribeToSessionUpdates { message ->
  if (message.eventType == SessionStateChangedEvent.ChangeType.SESSION_STARTED) {
    // A session has just been started
  }
}

1
2
3
4
5
6
7
8
9
10
11
// This subscription is maintained through a Braze cancellable, which will observe changes until the subscription is cancelled.
// You must keep a strong reference to the cancellable to keep the subscription active.
// The subscription is canceled either when the cancellable is deinitialized or when you call its `.cancel()` method.
let cancellable = AppDelegate.braze?.subscribeToSessionUpdates { event in
  switch event {
  case .started(let id):
    print("Session \(id) has started")
  case .ended(let id):
    print("Session \(id) has ended")
  }
}

1
2
3
4
5
6
7
8
for await event in braze.sessionUpdatesStream {
  switch event {
  case .started(let id):
    print("Session \(id) has started")
  case .ended(let id):
    print("Session \(id) has ended")
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// This subscription is maintained through a Braze cancellable, which will observe changes until the subscription is cancelled.
// You must keep a strong reference to the cancellable to keep the subscription active.
// The subscription is canceled either when the cancellable is deinitialized or when you call its `.cancel()` method.
BRZCancellable *cancellable = [AppDelegate.braze subscribeToSessionUpdates:^(BRZSessionEvent * _Nonnull event) {
  switch (event.state) {
    case BRZSessionStateStarted:
      NSLog(@"Session %@ has started", event.sessionId);
      break;
    case BRZSessionStateEnded:
      NSLog(@"Session %@ has ended", event.sessionId);
      break;
    default:
      break;
  }
}];

Step 2: Test session tracking (optional)

To test session tracking, start a session on your device, then open the Braze dashboard and search for the relevant user. In their user profile, select Sessions Overview. If the metrics update as expected, session tracking is working correctly.

Changing the default session timeout

You can change the length of time that passes before a session automatically times out.

• web
• android
• swift
• react native

1
2
// Sets the session timeout to 15 minutes instead of the default 30
braze.initialize('YOUR-API-KEY-HERE', { sessionTimeoutInSeconds: 900 });

1
2
<!-- Sets the session timeout to 60 seconds. -->
<integer name="com_braze_session_timeout">60</integer>

1
2
3
4
5
6
7
8
// Sets the session timeout to 60 seconds
let configuration = Braze.Configuration(
  apiKey: "<BRAZE_API_KEY>",
  endpoint: "<BRAZE_ENDPOINT>"
)
configuration.sessionTimeout = 60;
let braze = Braze(configuration: configuration)
AppDelegate.braze = braze

1
2
3
4
5
6
7
// Sets the session timeout to 60 seconds
BRZConfiguration *configuration =
  [[BRZConfiguration alloc] initWithApiKey:brazeApiKey
                                  endpoint:brazeEndpoint];
configuration.sessionTimeout = 60;
Braze *braze = [[Braze alloc] initWithConfiguration:configuration];
AppDelegate.braze = braze;