JavaScript Beacon API for Reliable Analytics Telemetry

The Beacon API is a specialized web API designed to send small amounts of analytical, diagnostic, and telemetry data from the browser to a web server asynchronously and reliably. Unlike standard HTTP requests that can be abruptly canceled when a user navigates away or closes a tab, the Beacon API guarantees that the browser queues and delivers the data in the background without delaying page unloads or degrading user experience.

The Problem with Traditional Data Transmission

Web analytics often capture metrics right when a user finishes a session or leaves a page. Historically, developers relied on XMLHttpRequest (XHR) or the fetch() API inside event listeners like unload or beforeunload.

These traditional methods introduce significant drawbacks during page transitions: * Dropped Requests: Asynchronous fetch or XHR requests are frequently aborted by the browser when the page unloads, resulting in lost analytics data. * UI Freezing: Using synchronous XHR forces the browser to delay the navigation until the server responds, creating a sluggish and frustrating experience for the user. * Keepalive Limitations: While fetch() with the { keepalive: true } flag addresses some of these issues, it has varying support edge cases and requires more verbose error handling.

How the Beacon API Solves the Problem

The Beacon API resolves these issues by handing off the data transmission process entirely to the browser. Once invoked, the browser queues the request and transmits the data over HTTP POST in the background, independent of the originating document’s lifecycle.

The core implementation relies on the navigator.sendBeacon() method:

navigator.sendBeacon(url, data);

• url: The destination endpoint where data should be transmitted.
• data: The payload, which can be an ArrayBuffer, Blob, DOMString, or FormData.

Key Benefits of navigator.sendBeacon()

• Asynchronous and Non-blocking: It executes entirely in the background, ensuring no latency during page transitions.
• Guaranteed Delivery: The browser ensures the payload is dispatched even after the document has been completely destroyed.
• Resource Optimization: The browser can batch or optimize network connections without competing with critical UI tasks.

Implementing Beacon with visibilitychange

For modern web applications, the most reliable event to send telemetry is visibilitychange, rather than the deprecated unload or beforeunload events. Mobile browsers frequently discard background tabs without firing the unload event.

document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'hidden') {
    const analyticsData = JSON.stringify({
      event: 'page_exit',
      timeSpent: performance.now(),
      path: window.location.pathname
    });

    const blob = new Blob([analyticsData], { type: 'application/json' });
    navigator.sendBeacon('/api/telemetry', blob);
  }
});

Constraints and Best Practices

• HTTP Method: The Beacon API exclusively sends HTTP POST requests.
• Payload Limits: Because it is designed for lightweight analytics, browsers typically restrict beacon payloads to 64 KB per request to prevent network congestion.
• No Server Response: navigator.sendBeacon() returns a boolean (true if queued, false if rejected due to browser limitations). It does not provide access to the server’s response headers or body, making it unsuitable for transactions requiring verification.