What's changed with sessions
A session is now the full arc of a user's visit to your app. What Embrace previously called a "session" is now a session part. What Embrace previously called a "stitched session" is now simply a session. No action is required from you, and no data was lost.
What a session means now
If you have ever described a user's experience in your app as a "session," you probably pictured the full arc of that visit: the moment they opened the app to the moment they stopped engaging, including brief periods where the app was backgrounded or a page wasn't being viewed. That is how most mobile teams think about it, and it is the standard for web teams.
Embrace used to be an outlier here. What most people call a session, we called a "stitched session," and we used "session" for the smaller component pieces representing individual user interactions. In the diagram below, the black box represents a duration of time where a user used an app. The dark grey boxes represent periods of user interactions with the app in the foreground, and the light grey are periods of background inactivity.
We call the black box a "session" and the grey boxes "session parts". We previously referred to the black box as "stitched sessions" and the dark grey boxes as "sessions".
| Concept | Old term | New term |
|---|---|---|
| A user's meaningful, end-to-end experience in your app | Stitched session | Session (user_session) |
| A single foreground or background period of the app | Session | Session part (session_part) |
A session may span multiple instances of the user foregrounding and backgrounding your app. Session parts are the building blocks of a session.
For the rest of this document, "session" refers to the new definition.
Change Phases
The rollout happened in two phases.
Phase 1 — Embrace SDKs
The new model shipped with the below version of our SDKs.
- Android: >= 9.0.0
- iOS: >= 7.0.0
- Web: >= 2.25.0
What this means:
- Existing data and metrics kept working. The session metrics you relied on before are still available in widgets and custom metrics.
- New SDK capabilities. You can define sessions more precisely, including ending a session yourself programmatically, and set properties at the new session scope. For details, see the changelog for each platform SDK you have instrumented, and the Android Upgrade Guide.
Phase 2 — Embrace platform UI
Labeling in the platform UI and dashboards now uses the new terminology. Wherever you previously saw "stitched sessions," you will see "sessions". Individual foreground and background periods are labeled "session parts."
All apps sending data before the release date experience a transitionary period, where in the dashboard you can switch between session-derived metrics and session-part-derived metrics. This switcher will last until 75% of incoming sessions are being sent from an SDK version above the threshold and 30 days have passed since the first session is sent on the new SDK version.
All existing dashboards, alerts, and custom metrics will continue to be session-part-derived. Over the coming months, we will be releasing many new session-derived metrics that can be utilized throughout the dashboard.
What this means for you
- Nothing broke, and nothing is required of you. These were non-breaking changes. Existing dashboards, widgets, alerts, and custom metrics continue to work based on their original definitions, using session parts where applicable.
session_partis still there when you need to reason about an individual foreground or background period.- Older SDK versions still report data. Apps running pre-upgrade SDK versions continue to send data and are represented under the new model.
We did not make these changes arbitrarily. Aligning on the industry definition lets us unlock more meaningful signals: app health, core vitals, issue density across real user experiences, and more.
Questions? Reach out on the community Slack or email support@embrace.io.