Skip to content

Session Management

Events collected by the SDK are annotated with a session identifier (ID). This session identifier is utilized to group events emitted by the SDK and can be used to retrieve events from a specific session.

The SDK manages the used session identifier using one of the two following strategies:

  • ActivityBased (Kotlin) / activityBased (Swift) / SessionStrategy.Activity (JavaScript): A session strategy that generates a new session ID after a certain period of app inactivity. The inactivity duration is measured by the minutes elapsed since the last log. The session ID is persisted to disk and survives app restarts.
  • Fixed (Kotlin) / fixed (Swift) / SessionStrategy.Fixed: A session strategy that never expires the session ID but does not survive process restart.

The minimal session strategy setup looks as follows:

Kotlin
// `ActivityBased` session strategy
Logger.start(
  // ...
  sessionStrategy = SessionStrategy.ActivityBased()
)

// `Fixed` session strategy
Logger.start(
  // ...
  sessionStrategy = SessionStrategy.Fixed
)
Java
// `ActivityBased` session strategy
Logger.start(
  // ...
  new SessionStrategy.ActivityBased()
);

// `Fixed` session strategy
Logger.start(
  // ...
  new SessionStrategy.Fixed()
);
Swift
// `activityBased` session strategy
Logger.start(
  // ...
  sessionStrategy: .activityBased()
)

// `fixed` session strategy
Logger.start(
  // ...
  sessionStrategy: .fixed()
)
Objective-C
// `activityBased` session strategy
[CAPLogger
  // ...
  sessionStrategy: [CAPSessionStrategy activityBased]
];

// `fixed` session strategy
[CAPLogger
  // ...
  sessionStrategy: [CAPSessionStrategy fixed]
];
JavaScript
// `activityBased` session strategy
init("<your-api-key>", SessionStrategy.Activity);

// `fixed` session strategy
init("<your-api-key>", SessionStrategy.Fixed);
JavaScript
// `activityBased` session strategy
init("<your-api-key>", SessionStrategy.Activity);

// `fixed` session strategy
init("<your-api-key>", SessionStrategy.Fixed);

Retrieving Session ID

The current session identifier can be retrieved when needed using the Logger getter. Session ID is only available after the Logger has been started.

Kotlin
Logger.sessionId
Java
Logger.getSessionId();
Swift
Logger.sessionID
Objective-C
[CAPLogger sessionID];
JavaScript
import { getSessionId } from '@bitdrift/react-native';

getSessionId();

Retrieving Session URL

Similarly, the full session permalink URL can be retrieved using the Logger getter. This is particularly helpful when integrating with external systems. Session URL is only available after the Logger has been started.

Kotlin
Logger.sessionUrl
Java
Logger.getSessionUrl();
Swift
Logger.sessionURL
JavaScript
import { getSessionUrl } from '@bitdrift/react-native';

getSessionUrl();

Generating New Session ID

It may be desirable to generate a new session identifier in response to specific user action(s) (e.g., user logging out) or other events.

A new session identifier can be generated using a simple method call:

Kotlin
Logger.startNewSession()
Java
Logger.startNewSession();
Swift
Logger.startNewSession()

Depending on the session strategy used, the new session identifier is generated in the following way:

  • ActivityBased (Kotlin) / activityBased (Swift) / Activity: A random, unique session identifier is generated each time thestartNewSession` method is called.
  • Fixed (Kotlin) / fixed (Swift): A session identifier is set to the identifier retrieved using the sessionIdGenerator (Kotlin) lambda / sessionIDGenerator (Swift) closure. This closure is passed to the initializer of the Fixed (Kotlin) / fixed (Swift) session strategy.

For the Fixed (Kotlin) / fixed (Swift) session strategy, a session ID generator can be passed in the following way:

Kotlin
var counter = 0;
Logger.start(
  // ...
  sessionStrategy = SessionStrategy.Fixed(sessionIdGenerator = { (++counter).toString() })
)

println(Logger.sessionId) // prints "1"

Logger.startNewSession()

println(Logger.sessionId) // prints "2"
Java
AtomicInteger counter = new AtomicInteger(0);
Logger.start(
  // ...
  new SessionStrategy.Fixed(() -> Integer.toString(counter.incrementAndGet()))
);

println(Logger.getSessionId()); // prints "1"

Logger.startNewSession();

println(Logger.getSessionId()); // prints "2"
Swift
var counter = 0
Logger.start(
  // ...
  sessionStrategy: .fixed {
    counter += 1;
    return \"(counter)"
  }
)

print(Logger.sessionID) // prints "1"

Logger.startNewSession()

print(Logger.sessionID) // prints "2"

Observing Session ID Changes

In the case of the ActivityBased (Kotlin) / activityBased (Swift) session strategy, the session identifier is managed on behalf of SDK customers and can change without their explicit request. For this reason, the SDK provides a way for customers to register for session identifier changes specific to this session strategy type:

Kotlin
Logger.start(
  // ...
  sessionStrategy = SessionStrategy.ActivityBased(
    inactivityThresholdMins = 30,
    onSessionIdChanged = { newSessionId ->
      // Do something with the new session ID
    }
  )
)
Java
Logger.start(
  // ...
  new SessionStrategy.ActivityBased(
    30, //inactivityThresholdMins
    newSessionId -> {
      // Do something with the new session ID
      return Unit.INSTANCE;
    }
  )
);
Swift
Logger.start(
  // ...
  sessionStrategy: .activityBased(
    inactivityThresholdMins: 30,
    onSessionIDChanged: { newSessionID in
      // Do something with the new session ID
    }
  )
)