Skip to content

Tracking 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.

By default, a session starts when openSession() is first called. If your app goes to the background, the session will remain active for 10 seconds (unless you change the default session timeout) or the user closes your app. Keep in mind, if the user closes your app while its in the background, session data may not be set to Braze until they reopen the app.

Calling closeSession() will not immediately end the session. Instead, it will end the session after 10 seconds if openSession() isn’t called again by the user starting another activity.

By default, a session starts when you call Braze.init(configuration:). This occurs when the UIApplicationWillEnterForegroundNotification notification is triggered, meaning the app has entered the foreground.

If your app goes to the background, UIApplicationDidEnterBackgroundNotification will be triggered. The session will remain active for 10 seconds (unless you change the default session timeout) or the user closes your app.

By default, a session starts when you first call braze.openSession(). The session will remain active for up to 30 minutes of inactivity (unless you change the default session timeout) or the user closes the app.

Subscribing to session updates

Step 1: Subscribe to updates

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

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
  }
}

If you register a session end callback, it fires when the app returns to the foreground. Session duration is measured from when the app opens or foregrounds, to when it closes or backgrounds.

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")
  }
}

To subscribe to an asynchronous stream, you can use sessionUpdatesStream instead.

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

At this time, subscribing to session updates are not supported for the Web Braze SDK.

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.

The sessions overview section of a user profile showing the number of sessions, last used date, and first used date.

Changing the default session timeout

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

By default, the session timeout is set to 10 seconds. To change this, open your braze.xml file and add the com_braze_session_timeout parameter. It can be set to any integer greater than or equal to 1.

1
2

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

By default, the session timeout is set to 10 seconds. To change this, set sessionTimeout in the configuration object that’s passed to init(configuration). It can be set to any integer greater than or equal to 1.

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;

By default, the session timeout is set to 30 seconds. To change this, pass the sessionTimeoutInSeconds option to your initialize function. It can be set to any integer greater than or equal to 1.

1
2

// Sets the session timeout to 15 minutes instead of the default 30
braze.initialize('YOUR-API-KEY-HERE', { sessionTimeoutInSeconds: 900 });
Github   Edit this page on GitHub
HOW HELPFUL WAS THIS PAGE?
New Stuff!