Overview
What is a session?
A session in Heap is a period of activity from a single user in your app or website. It can include many pageviews or events. On web, a session ends after 30 minutes of pageview inactivity from the user. On mobile, a session ends after 5 minutes of inactivity, regardless of whether the app’s background or foreground state.
Per our data model, users conduct sessions in which they complete interactions like pageviews and events, which you then track to understand how your product or service is being used.
Sessionization is the process by which that period of activity is stored as a session. Understanding how sessionization works can help you leverage session analysis to surface insights about your users.
Session behavior differs across platforms. See the platforms sections below for info on when sessions may end.
All Platforms
On all platforms, each new foreground event will extend the session for 5 minutes, whether it’s an autocaptured event or a custom event.
If a background custom event happens within 5 minutes of a foreground event, then it will belong to the same session, but it will NOT extend the duration of the session. The session will still end after 5 minutes of inactivity based on the foreground events.
A background event will generate a new session if it doesn’t start within 5 minutes of a foreground event. If two background events happen within 5 minutes of each other but without a foreground event linking them, then they will create two distinct session IDs.
Calls to heap.identify will also extend the sessions for 5 minutes, regardless of whether they occurred in the foreground or the background.
Mobile (iOS, Android, React Native)
When a session ends on mobile may vary based on the state of these background or foreground events.
Autocaptured Events
iOS: An autocaptured event in the background will also extend the session for 5 minutes.
You can disable autocapture when an app has been backgrounded via the disableAutocaptureWhenBackgrounded API.
Android: No event is ever autocaptured while the app is backgrounded, so this rule doesn’t apply.
React Native: React Native behavior will match the platform it’s running on.
Custom Events
iOS: A custom event in the background that happens within 5 minutes of a foreground event will belong to the same session as that event and will extend the duration of the session.
Android: Such events will use a synthetic/unique session ID and won’t extend the duration of the session (session will end after 5 minutes of inactivity based on foreground events only).
On iOS, you can use disableAutocaptureWhenBackgrounded to ensure autocaptured events won’t be tracked when the app is in the background. Custom events won’t be impacted by this flag.
React Native: React Native behavior will match the platform it’s running on.
Frequently Asked Questions
How do webviews impact session behavior?
A session involving webviews will use a mix of our web SDK and our mobile SDK. As a result, for any given session, two session IDs will be created (one for the web portion and one for the native portion).
Webviews can be distinguished from true website visits by looking at the Browser property of a session. For example, webviews on iOS will have a browser value such as Mobile Safari UIWebView.
How do server-side events impact session behavior?
Session IDs are generated by our SDKs. Because server-side events are sent independently, they generate their own session ID that can’t be linked to a corresponding client-side session ID, even if the server-side event occurs in the same time window as client-side events.
How are anonymous mobile users tracked across sessions?
Heap tracks anonymous mobile users as follows:
- iOS: user ID is stored in `NSUserDefaults`
- Android: user ID is stored in `android SharedPreferences`
- React Native: Persisted user info is entirely backed by the native SDK