Sessions

A session is a continuous stretch of time while the app is in the foreground. The app sends two events with a shared session_id:

• session_start — when it comes to the foreground;
• session_end — when it goes to the background, with a duration_ms field.

Client rulesCopy Anchor Link

1. A new session_id every time the app comes to the foreground. The UUID is generated on the client; both events of a session carry the same session_id and install_id.
2. The client calculates duration_ms: time in the foreground in milliseconds, from 0 to 86,400,000. Use a monotonic clock (systemUptime, SystemClock.elapsedRealtime, performance.now), not a wall-clock difference: the user may change the clock during a session.
3. Short trips to the background end a session too. The server doesn't stitch sessions across pauses. If you want to ignore momentary switches (the notification shade, a system dialog), react to "background" rather than "inactive", as the recipes do.
4. No foreground means activity-based sessions. For bots and backends, a session is a series of user requests with no pauses longer than 30 minutes; see Bots and backends.

Which lifecycle events start and end a session on each platform is covered in Where to initialize analytics.

How metrics are calculatedCopy Anchor Link

What follows from this:

• A lost session_end doesn't lose the session: it is counted by session_start but left out of the average duration. If session_end events get lost often, the average duration is understated.
• Resending the same event doesn't inflate the numbers: every metric is calculated over unique identifiers.
• Two session_end events for one session (the client recalculated the duration after coming back): the maximum is used.
• A session that spans midnight counts the person as active on both days, while the session itself belongs to the day of its session_start.

Days in reports follow the app's time zone, not the device's.

Version and environmentCopy Anchor Link

The batch context describes the device and the build: platform, os_name, os_version, app_version, app_build, device_model, device_type, locale, environment. An event's context field overrides the batch context field by field. This comes in handy when the offline queue holds events from an older app version: each event goes out with its own version.

environment is production (default) or development. Reports show production, and development is turned on with the Environment switch. Send development from debug builds so that tests don't skew the numbers.