Tracking Custom Events
Relevant source files
The following files were used as context for generating this wiki page:
Tracking Custom Events in Glimpse allows developers to capture specific user interactions that fall outside the scope of automatic tracking. This system provides a manual API to record meaningful business metrics, user behaviors, and UI performance data, enriching the real-time analytics stream with domain-specific context.
The feature is primarily implemented through the track and trackOnView functions within the analytics-web package. These functions allow for explicit event triggering via JavaScript calls or visibility-based triggers linked to DOM elements. All custom events are enriched with session metadata, viewport information, and device context before being queued for transport to the backend.
Sources: packages/analytics-web/index.js, packages/analytics-web/events/track.js:1-14, packages/analytics-web/events/trackonView.js:3-12
Core Tracking Architecture
The custom tracking system follows a modular flow: identification of the project, creation of the event payload, and buffered transport.
Event Lifecycle and Data Flow
When a custom event is triggered, the SDK first verifies the presence of a projectId associated with the current GlimpseTracker instance. If initialized, it retrieves the current sessionId and constructs a comprehensive event object. This object includes the event name, a timestamp, and various context properties (URL, referrer, viewport, user agent).
The diagram above illustrates the logic path from a manual API call to the eventual network request.
Sources: packages/analytics-web/events/track.js:5-13, packages/analytics-web/core/event.js:6-38, packages/analytics-web/transport/sender.js:52-69
Manual Event API
The primary interface for custom tracking is the track function. It is exported via the global window.GlimpseTracker object for use in web applications.
The track Function
This function accepts an event name and an optional properties object.
| Parameter | Type | Description |
|---|---|---|
name | string | The identifier for the event (e.g., 'Purchase', 'CTA Click'). |
properties | object | Optional key-value pairs providing extra context (e.g., { amount: 42 }). |
Sources: packages/analytics-web/events/track.js:4, test/demo.html:150-170
Event Object Structure
The createEvent utility generates a standardized schema for all manual tracks.
// packages/analytics-web/core/event.js:6-14
export function createEvent(projectId, sessionId, name, properties) {
const currentPath = location.pathname + location.search + location.hash;
const evt = {
projectId,
event: name,
timestamp: Date.now(),
sessionId,
properties: properties || {},
// ...
Sources: packages/analytics-web/core/event.js:6-14
Visibility Tracking (trackOnView)
Glimpse provides a specialized API for tracking when specific elements enter the user's viewport. This is built on the IntersectionObserver API.
Configuration Options
The trackOnView function allows for fine-grained control over visibility triggers.
- Threshold: Defines the percentage of the element that must be visible (default: 0.5).
- Once: Boolean determining if the event should only fire the first time the element is seen (default: true).
Sources: packages/analytics-web/events/trackonView.js:4-5
Implementation Logic
The system uses a WeakSet to keep track of elements that have already been viewed, preventing duplicate events when the once option is enabled.
The sequence diagram shows how visibility events are managed to avoid redundant data.
Sources: packages/analytics-web/events/trackonView.js:1-35
Automatic Custom-Ready Tracking
While "Custom Events" usually refer to manual calls, Glimpse supports "Custom-Ready" automatic tracking. By adding specific data attributes to HTML elements, developers can trigger events without writing JavaScript.
Supported Data Attributes
| Attribute | Use Case | Description |
|---|---|---|
data-track | Button Clicks | Automatically tracks clicks on buttons or CTAs. |
data-track-name | Event Naming | Provides a custom name for the data-track or data-track-view event. |
data-track-view | View Tracking | Automatically sets up visibility tracking for the element. |
Sources: packages/analytics-web/events/auto.js:48-55, packages/analytics-web/events/auto.js:116-121
Transport and Buffering
Custom events are not sent immediately. To optimize performance and reduce network overhead, they are handled by a sender module that implements buffering.
- Buffer Size: The sender collects up to 10 events before flushing.
- Flush Interval: If the buffer is not full, it flushes every 5000ms.
- Retries: Failed requests are retried up to 3 times with exponential backoff.
Sources: packages/analytics-web/transport/sender.js:3-7, packages/analytics-web/transport/sender.js:52-69
Summary
Tracking Custom Events in Glimpse bridges the gap between general session data and specific business logic. By leveraging the track and trackOnView APIs, along with declarative data-track attributes, developers can capture high-fidelity interaction data. The underlying architecture ensures this data is enriched with session context and delivered efficiently through a buffered transport layer.