Introduction to the Beacon API

Originally published at:

The Beacon API makes it easy for web developers to send small amounts of data, such as analytics or diagnostics data, back to the server asynchronously while the current page is unloading. In this article, we’ll look at some of the problems the Beacon API solves, and show you how to use the API.

Without the Beacon API, sending data back to your server when the user navigates away from a page can be trickier than it seems. You don’t want to delay the next page from loading, as this would harm the user’s experience of your site. Yet you don’t want to loose valuable information that could help improve your site: sending the data too early might mean you loose valuable information that you could have captured if you’d waited a fraction longer.

A typical solution to that sends analytics data to the server as the document unloads might look something like this:

window.addEventListener('unload', function(event) {
  var xhr = new XMLHttpRequest(),
    data = captureAnalyticsData(event);'post', '/log', false);

function captureAnalyticsData(event) {
  return 'sample data';

An unload event handler, that submits data via an Ajax request. When the page unload event fires, the data is captured via the captureAnalyticsData function, and sent to the server via an Ajax request. Note the third parameter to is false, indicating the Ajax request is synchronous. Browsers typically ignore asynchronous requests made during an unload handler, so any such Ajax request has to be synchronous. As it’s synchronous, the browser has to wait for the request to complete before it can unload the document and display the next page. This extra waiting around can lead to the perception of poor performance.

Other techniques used instead of a synchronous Ajax request include setting the src of an Image object in the unload handler. The browser will wait for the Image to load before unloading the document, during which time data can be submitted to the server. However, this still has the same problem: the unloading of the current document will be delayed while the request, this time for the Image, completes, which can lead to the perception of poor performance.

The Beacon API was created to help solve these issues. It defines an interface that lets developers send small amounts of data to the web server asynchronously. It consists of just one method, sendBeacon, that is attached to the navigator object. sendBeacon takes two parameters, the URL you want to submit data to and the data to be submitted:

window.addEventListener('unload', function(event) {
  var data = captureAnalyticsData(event);
  navigator.sendBeacon('/log', data);

Continue reading this article on SitePoint

Interesting article. The term API comes up so much these days, in so many contexts, that it would be worth pointing out at the start of the article that this is a new browser API (or HTML5, or whatever) just to make the context clear. It became more obvious as the article proceeded, but there are so many new things swirling around out there these days (tools, frameworks and so on) that there can’t be too much context, IMHO!

1 Like

Agreed. A couple additional example can’t hurt either. If you know an example (e.g., analytics), when something is new (read: being learned) a couple additional examples help give you a deeper feel for the tool.

Otherwise, good stuff.

This topic was automatically closed 91 days after the last reply. New replies are no longer allowed.