Client-side Session Management
Relevant source files
The following files were used as context for generating this wiki page:
Client-side session management in the Glimpse project is responsible for tracking user interactions within a discrete browsing window. Adhering to the core philosophy of "tracking sessions, not people," the system utilizes short-lived identifiers and browser storage to maintain state without identifying individuals across different devices or long periods.
The system captures the lifecycle of a user's visit, starting from the initialization of the web SDK and concluding when the user navigates away or closes the tab. This management layer ensures that every event sent to the backend is associated with a specific project and session context, enabling real-time visualization of traffic patterns.
Sources: PROJECT_OUTLINE.md:5-7, packages/analytics-web/events/auto.js:141-143
Session Lifecycle and Storage
The SDK manages session state primarily through the browser's sessionStorage. This ensures that session data is persisted during page reloads but cleared when the tab or window is closed.
Key Lifecycle Events
- Session Start: Automatically tracked when the script loads on the page.
- Path Persistence: The system tracks the current and previous URL paths within the session context to maintain navigation history.
- Session End: Triggered via the
beforeunloadevent to signal the termination of the active user session.
The following flowchart illustrates how the client-side session is initialized and tracked through page navigation:
The diagram shows the sequence from SDK initialization to session termination, highlighting the use of sessionStorage for path tracking.
Sources: packages/analytics-web/events/auto.js:9-11, packages/analytics-web/events/auto.js:141-143, packages/analytics-web/core/event.js:4-39
Event Context and Metadata
Every session-linked event is enriched with a comprehensive context object. This object includes hardware specifications, localization data, and network information to provide a detailed view of the session environment without compromising personal identity.
Session Context Structure
| Field | Source | Description |
|---|---|---|
sessionId | SDK Logic / Worker | Unique identifier for the current browser session. |
previousPath | sessionStorage | The URL of the page the user was on before the current action. |
viewport | window.innerWidth/Height | The dimensions of the visible browser area. |
screen | window.screen | Physical screen resolution and color depth. |
timezone | Intl.DateTimeFormat | The user's local timezone. |
connection | navigator.connection | Network type (e.g., 4g) and data saver status. |
Sources: packages/analytics-web/core/event.js:4-39, app/workers/eventWorker.ts:101-103
Backend Synchronization and TTL
While the client manages the session ID and immediate state, the backend worker enforces session duration and active status using Redis.
- Identifier Generation: If the client does not provide a session ID, the worker generates a UUID v7 (time-ordered) prefixed with
sess_. - Redis State: The session metadata (including GeoIP data) is stored in Redis with a Time-To-Live (TTL) of 300 seconds (5 minutes).
- Active Session Tracking: Session IDs are added to a Redis Set (
active_sessions:{projectId}) to calculate real-time user counts.
This sequence shows how the client-provided session data is synchronized with Redis to manage timeouts and active user metrics.
Sources: app/workers/eventWorker.ts:100-140, PROJECT_OUTLINE.md:129-135
Transport and Buffering
To optimize performance and minimize network overhead, session events are managed through a buffering transport layer before being sent to the /event endpoint.
- Client-side Buffer: Events are queued until the buffer reaches 10 items or a 5000ms interval is met.
- Retry Logic: The transport layer implements a maximum of 3 retries for failed event transmissions.
- Keepalive: The
fetchAPI is used withkeepalive: trueto ensure session end events are successfully transmitted even if the page is closing.
Sources: packages/analytics-web/transport/sender.js:3-15, packages/analytics-web/transport/sender.js:58-75
Summary
Client-side session management in Glimpse focuses on anonymous, real-time tracking. By utilizing sessionStorage for path history and UUID v7 for session identifiers, the system provides a robust framework for visualizing user journeys. The integration with a 300-second Redis TTL ensures that "active" users are accurately represented in the live dashboard while maintaining the project's privacy-first philosophy.
Sources: PROJECT_OUTLINE.md:129-135, app/workers/eventWorker.ts:133-134