Web Analytics SDK Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Glimpse Web Analytics SDK is a client-side JavaScript library designed to track user sessions and events in real-time. It operates under the core philosophy of tracking sessions rather than individual identities, providing developers with a clear view of website traffic and user behavior through both automatic and manual event capture.
The SDK integrates into web applications via a script tag, identifying projects through a mandatory data-project-id attribute. Once initialized, it manages session lifecycles, collects rich contextual metadata (such as viewport size, device info, and network status), and transmits this data to the Glimpse backend for visualization on live maps and dashboards.
Sources: PROJECT_OUTLINE.md:5-10, packages/analytics-web/index.js:1-12
Initialization and Configuration
The SDK is loaded into a web page and initializes by detecting its own script tag to extract configuration parameters. The primary configuration requirement is the projectId, which scopes all collected data to a specific application in the Glimpse ecosystem.
The SDK exposes a global window.GlimpseTracker object, making its API accessible for manual event tracking and specialized visibility monitoring.
Sources: packages/analytics-web/index.js:4-22
Global Tracker API
| Property | Description |
|---|---|
projectId | The unique identifier for the current project. |
track | Function for manual event tracking. |
trackOnView | Function for tracking element visibility events. |
Sources: packages/analytics-web/index.js:14-18
Event Structure and Context
Every event generated by the SDK, whether automatic or manual, is enriched with a comprehensive context object. This ensures that every user action is tied to the technical and geographic environment of the session.
Context Metadata
The createEvent function captures the following environment details:
- Navigation: Current URL, path (including search/hash), referrer, and the
previousPathwithin the session. - Device: User agent, language, and timezone.
- Screen: Viewport dimensions, full screen resolution, and color depth.
- Network: Effective connection type (e.g., 4g, wifi) and "Save Data" preferences if available via
navigator.connection.
Sources: packages/analytics-web/core/event.js:4-38
Automatic Event Tracking
When a valid projectId is provided, the SDK automatically initiates tracking for a variety of common user interactions and lifecycle events.
Lifecycle and Navigation
The SDK captures the start and end of user sessions automatically using browser events.
- Session Start: Fires immediately upon script initialization.
- Page View: Captures the current path and referrer.
- Session End: Triggered by the
beforeunloadevent when a user navigates away or closes the tab.
Sources: packages/analytics-web/events/auto.js:4-11, packages/analytics-web/events/auto.js:126-128
User Engagement Metrics
The SDK monitors deep engagement through scroll depth and visibility changes.
| Event Name | Trigger Condition | Data Collected |
|---|---|---|
Scroll Depth | User reaches 10%, 25%, 50%, 75%, 90%, or 100% of page height. | depth (percentage) |
Page Hidden | Tab becomes inactive or browser is minimized. | N/A |
Page Visible | User returns to the tab. | N/A |
Outbound Link Click | User clicks a link where the host differs from the current location. | url |
File Download | Clicks on links ending in common extensions (pdf, zip, exe, etc.). | url, fileType |
Sources: packages/analytics-web/events/auto.js:14-43, packages/analytics-web/events/auto.js:84-119
Error Reporting
The SDK acts as a basic error monitoring tool by listening for global browser errors and unhandled promise rejections.
- JavaScript Error: Captures the message, source file, line/column numbers, and stack trace.
- Unhandled Promise Rejection: Captures the rejection reason and stack trace.
Sources: packages/analytics-web/events/auto.js:101-114
Visibility Tracking
The SDK provides specialized tracking for when specific elements enter the user's viewport using the IntersectionObserver API.
Developers can implement this by adding data-track-view and data-track-name attributes to HTML elements, or by using the trackOnView API for more granular control, such as custom visibility thresholds.
Sources: packages/analytics-web/events/auto.js:47-73, test/demo.html:135-143
Summary
The Web Analytics SDK is a robust entry point for the Glimpse platform, focusing on automated collection of session-based data. By combining automatic lifecycle tracking with detailed environmental context and engagement metrics like scroll depth and visibility, it provides a comprehensive dataset for real-time visualization without requiring extensive manual instrumentation by the developer.