SDK Transport Layer
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The SDK Transport Layer is a critical component of the Glimpse analytics platform, responsible for the reliable delivery of telemetry data from the client-side environment to the backend ingestion API. It acts as the final stage of the Analytics Web SDK, bridging the gap between event capture and server-side processing.
The layer is designed with performance and reliability in mind, utilizing local buffering to minimize network overhead and a retry mechanism to handle transient communication failures. It ensures that events such as page views, custom interactions, and system errors are transmitted efficiently without degrading the user experience on the host website.
Sources: PROJECT_OUTLINE.md, packages/analytics-web/transport/sender.js:1-5
Architecture and Components
Client-Side Buffering
To optimize network utilization, the transport layer employs a buffering strategy. Events are not sent immediately upon capture but are instead placed into an internal queue. The buffer flushes based on two primary triggers: a maximum size threshold or a time-based interval.
| Configuration Variable | Default Value | Description |
|---|---|---|
BUFFER_SIZE | 10 | The maximum number of events to hold before triggering a flush. |
FLUSH_INTERVAL | 5000ms | The time to wait before automatically flushing the buffer if the size limit isn't reached. |
MAX_RETRIES | 3 | The number of times the transport will attempt to resend a failed event batch. |
| Sources: packages/analytics-web/transport/sender.js:3-7 |
Event Transmission (Fetch API)
The transport layer utilizes the browser's fetch API for data transmission. Requests are configured with specific headers and modes to ensure compatibility with modern web security standards.
- Endpoint:
http://localhost:3000/event - Method:
POST - Mode:
cors(Cross-Origin Resource Sharing) - Keepalive: Enabled, allowing the request to continue even if the page is unloaded.
- Credentials:
omit, ensuring no cookies or sensitive credentials are sent with the analytics data.
Sources: packages/analytics-web/transport/sender.js:1, 23-28
Lifecycle of an Event
The following diagram illustrates the path an event takes from the moment it is enqueued by an tracking function until it is dispatched to the backend.
The enqueueEvent function manages the eventBuffer and coordinates with flushTimer to ensure data is sent in a timely manner.
Sources: packages/analytics-web/transport/sender.js:46-64
Data Flow: Client to Worker
The transport layer interfaces with the Backend API, which validates the payload before handing it off to the asynchronous processing system.
The API controller extracts metadata such as the client's IP address (via X-Forwarded-For or request context) and User-Agent, which are appended to the event before being queued for the worker.
Sources: app/api/controller/event.controller.ts:15-53, app/workers/eventWorker.ts:85-98
Implementation Details
Transmission Logic
The send function iterates through a batch of events and attempts to transmit them. It includes an internal attemptSend function that handles exponential backoff (calculated as 1000ms * attempts) for retries.
function attemptSend() {
attempts++;
fetch(ENDPOINT, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: payload,
keepalive: true,
mode: 'cors'
}).catch((err) => {
if (attempts < MAX_RETRIES) {
setTimeout(attemptSend, 1000 * attempts);
} else {
console.error('Failed to send analytics events:', err);
}
});
}
Sources: packages/analytics-web/transport/sender.js:15-32
Integration with Auto-Tracking
The transport layer is the default export for the web analytics package and is consumed by various tracking modules. For instance, the auto.js module uses the track function, which internally calls the transport's enqueueEvent.
Key events handled by this transport include:
- Visibility Changes: Tracking "Page Hidden" and "Page Visible".
- Outbound Links: Clicks leading away from the host domain.
- File Downloads: Clicks on links with extensions like
.pdf,.zip, etc. - Form Submissions: Capturing form actions.
- Session Termination: A final
Session Endevent is triggered via thebeforeunloadlistener.
Sources: packages/analytics-web/events/auto.js:82-132
Conclusion
The SDK Transport Layer provides a robust foundation for data collection in Glimpse. By balancing immediate delivery through threshold-based flushing with reliability through retry logic and keepalive support, it ensures that high-fidelity session data reaches the Event Worker for real-time visualization and historical analysis.