BugSnag tracks the number of “sessions” that happen within your application. This allows you to compare stability scores between releases and helps you to understand the quality of your releases.
Sessions are captured and reported by default. This behavior can be disabled using the autoTrackSessions
configuration option.
These docs are for the @bugsnag/react-native
package, which supports React Native v0.60 and above.
If you’re using the previous bugsnag-react-native
package, we recommend upgrading to the latest release, unless you’re using a version of React Native older than 0.60. Documentation for bugsnag-react-native
can be found on our legacy pages.
BugSnag will automatically report a session each time the app is launched or enters the foreground after being in the background for at least 30 seconds.
If you want control over what is deemed a session, you can switch off automatic session tracking with the autoTrackSessions
option, and manage the session lifecycle using startSession
, pauseSession
and resumeSession
on the Bugsnag
client.
You should call these methods at the appropriate time in your application’s lifecycle when you wish to have an active session. Any errors which occur in your application outside of a session will still be reported to BugSnag but will not count towards your application’s stability score.
startSession
Starts a new session to which subsequent handled and unhandled events will be attributed to.
Bugsnag.startSession()
Bugsnag.startSession();
[Bugsnag startSession];
If there is already an active session, it will be replaced with a new one. Use resumeSession if you only want to start a session when one doesn’t already exist.
pauseSession
Prevents further events being attributed to the current session until the session is resumed or a new session is started.
Bugsnag.pauseSession()
Bugsnag.pauseSession();
[Bugsnag pauseSession];
This can be advantageous if, for example, you do not wish the stability score to include crashes in a background service.
resumeSession
Resumes tracking events against the current session, if it was previously paused. If there is was no previous session, a new session is started. This method returns true
if there was a session to resume or false
if a new session was created.
if (Bugsnag.resumeSession()) // ...
if (Bugsnag.resumeSession()) // ...
if ([Bugsnag resumeSession]) // ...
Sessions are stored in memory for the lifetime of the application process and are not persisted on disk. Therefore calling this method on app startup would start a new session, rather than continuing any previous session.
For more information about managing sessions, see our platform-specific guides:
The data captured in a session can be customized using a callback as part of your BugSnag configuration. As sessions start when an app launches, which is before the JavaScript runtime has started, session callbacks are only available in the iOS and Android libraries.
Android:
Configuration config = Configuration.load(this);
config.addOnSession(new OnSessionCallback() {
@Override
public boolean onSession(Session session) {
String userId = getMyUserIdentifier(); // a custom user resolver
session.setUser(userId, null, null);
return true; // Return false to discard
}
});
Bugsnag.start(this, config);
iOS:
BugsnagConfiguration *config = [BugsnagConfiguration loadConfig];
[config addOnSessionBlock:^(BugsnagSession *session) {
NSString *userId = [self getMyUserIdentifier]; // a custom user resolver
[session setUser:userId withEmail:nil andName:nil];
return YES; // Return false to discard
}];
[Bugsnag startWithConfiguration:config];
The return value from the callback block determines whether the session will be delivered to BugSnag and so can be used to discard sessions if required.
For more information about session callbacks, see our platform-specific guides:
We recommend adding callbacks through the addOnSession
configuration option to ensure that it is registered as soon as BugSnag starts. However, the following methods are provided to allow callbacks to be added and removed whilst the application is running:
Android:
OnSessionCallback cb = new OnSessionCallback() { /* ... */ };
Bugsnag.addOnSession(cb);
...
Bugsnag.removeOnSession(cb);
iOS:
BugsnagOnSessionBlock cb = ^BOOL(BugsnagSession *session) { /* ... */ };
[Bugsnag addOnSessionBlock:cb];
// ...
[Bugsnag removeOnSessionBlock:cb];
For more information about adding and removing session callbacks, see our platform-specific guides:
The session callbacks available to the native libraries provide a “session” parameter that represents a session that is about to be sent to BugSnag. The object contains properties and methods for you to query and update the captured data.
For full details, see our platform-specific guides: