Auto-Tracking Features
Relevant source files
The following files were used as context for generating this wiki page:
The Auto-Tracking system in Glimpse is a client-side mechanism designed to capture user interactions and lifecycle events without requiring manual instrumentation for every action. It is implemented as a part of the analytics-web SDK and is activated automatically when a valid data-project-id is detected on the integration script.
The system captures a wide range of metrics including navigation (page views), engagement (scroll depth, visibility), interactions (clicks, form submissions), and technical health (JavaScript errors). These events are context-enriched with session data, viewport dimensions, and hardware information before being dispatched to the backend.
Sources: packages/analytics-web/index.js:12-20, PROJECT_OUTLINE.md:144-150
Initialization and Lifecycle
Auto-tracking is conditionally loaded based on the presence of a project identifier. When the SDK initializes, it searches the DOM for a script tag containing the data-project-id attribute. If found, it dynamically imports the auto-tracking module.
Execution Flow
The diagram shows the logic flow from script detection to the firing of initial lifecycle events.
Sources: packages/analytics-web/index.js:3-23, packages/analytics-web/events/auto.js:4-10
Engagement Tracking
Glimpse monitors how users consume content through scroll depth and element visibility triggers.
Scroll Depth Tracking
The system tracks vertical progress through a page at specific milestones: 10%, 25%, 50%, 75%, 90%, and 100%. It uses a Set named reachedMilestones to ensure each milestone is only tracked once per page load.
Sources: packages/analytics-web/events/auto.js:13-37
Element Visibility
Specific UI elements can be tracked automatically using the IntersectionObserver API. Elements marked with the data-track-view attribute trigger an "Element Viewed" event when at least 50% of the element becomes visible in the viewport.
| Attribute | Description |
|---|---|
data-track-view | Required. Serves as the unique identifier or toggle for visibility tracking. |
data-track-name | Optional. A human-readable name for the element used in reporting. |
Sources: packages/analytics-web/events/auto.js:43-70, test/demo.html:112-115
Interaction Tracking
User interactions with links, buttons, and forms are captured via global event listeners.
Link and File Tracking
The SDK distinguishes between internal navigation, outbound links, and file downloads.
- Outbound Links: Triggered when a clicked
<a>tag points to a different host thanwindow.location.host. - File Downloads: Detects clicks on links ending in common extensions such as
.pdf,.zip,.docx, and.exe.
Button and Form Tracking
Buttons with the data-track attribute are automatically instrumented. Form submissions are captured globally, recording the formAction (the destination URL) of the submitted form.
Sources: packages/analytics-web/events/auto.js:82-91, packages/analytics-web/events/auto.js:106-121, packages/analytics-web/events/auto.js:131-136
Technical and State Tracking
The auto-tracker monitors the environment for health issues and state changes.
- Error Tracking: Listens for
window.errorandunhandledrejection. It captures the error message, source file, line/column numbers, and stack traces. - Visibility Change: Tracks when the browser tab is hidden or made visible using the
visibilitychangeevent, firing "Page Hidden" or "Page Visible" respectively. - Session Termination: Fires a "Session End" event during the
beforeunloadlifecycle phase to attempt capturing the end of user activity.
Sources: packages/analytics-web/events/auto.js:73-80, packages/analytics-web/events/auto.js:94-104, packages/analytics-web/events/auto.js:124-126
Event Structure and Context
Every auto-tracked event is enriched with a comprehensive context object created by the createEvent core function. This ensures that even automatic events carry technical metadata.
Event Data Model
This diagram represents the structure of the data sent to the backend as defined in the core event logic and database schema.
Sources: packages/analytics-web/core/event.js:6-38, packages/db/prisma/schema.prisma:24-44
Captured Metadata Fields
| Field Category | Key Data Points |
|---|---|
| Navigation | URL, Path, Referrer, Previous Path (from sessionStorage) |
| Environment | User Agent, Language, Timezone |
| Hardware | Viewport Size, Screen Resolution, Color Depth |
| Network | Effective Connection Type (e.g., 4g), Save Data preference |
Sources: packages/analytics-web/core/event.js:14-35
Summary
The auto-tracking features of Glimpse provide a "zero-config" entry point for website analytics. By leveraging standard DOM APIs like IntersectionObserver and global event listeners, the SDK captures a high-fidelity stream of user behavior—ranging from content consumption (scroll) to technical failures (JS errors)—while maintaining session continuity and environmental context.