Navigator.sendBeacon()

The navigator.sendBeacon() asynchronously transfers a small amount of data over HTTP to a web server.

Syntax

navigator.sendBeacon(url, data);

Parameters

url

The url parameter indicates the resolved URL to which the data is to be transmitted.

data

The data parameter is an ArrayBuffer, ArrayBufferView, Blob, DOMString, FormData, ReadableStream, or URLSearchParams object containing the data to be transmitted.

Return values

The sendBeacon() method returns true if the user agent is able to successfully queue the data for transfer, Otherwise it returns false.

Description

This method addresses the needs of analytics and diagnostics code that typically attempts to send data to a web server prior to the unloading of the document. Sending the data any sooner may result in a missed opportunity to gather data. However, ensuring that the data has been sent during the unloading of a document is something that has traditionally been difficult for developers, because user agents typically ignore asynchronous XMLHttpRequests made in an unload handler.

To solve this problem, analytics and diagnostics code have historically made a synchronous XMLHttpRequest call in an unload or beforeunload event handler to submit the data. The synchronous XMLHttpRequest blocks the process of unloading the document, which in turn causes the next navigation appear to be slower. There is nothing the next page can do to avoid this perception of poor page load performance, and the result is that the user perceives that the new web page is slow to load, even though the true issue is with the previous page.

There are other workaround techniques which have been used to ensure that this kind of data is submitted. One such technique is to delay the unload in order to submit data by creating an <img> element and setting its src attribute within the unload handler. As most user agents will delay the unload to complete the pending image load, data can be submitted during the unload. Another technique is to create a no-op loop for several seconds within the unload handler to delay the unload and submit data to a server.

Not only do these techniques represent poor coding patterns, some of them are unreliable and all of them result in the perception of poor page load performance for the next navigation.

The following example shows a theoretical analytics code that attempts to submit data to a server by using a synchronous XMLHttpRequest in an unload handler. This results in the unload of the page to be delayed.

window.addEventListener("unload", logData, false);

function logData() {
  var client = new XMLHttpRequest();
  client.open("POST", "/log", false); // third parameter indicates sync xhr
  client.setRequestHeader("Content-Type", "text/plain;charset=UTF-8");
  client.send(analyticsData);
}

This is where sendBeacon() comes in. By using the sendBeacon() method, the data is transmitted asynchronously to the web server when the User Agent has an opportunity to do so, without delaying the unload or affecting the performance of the next navigation. This solves all of the problems with submission of analytics data: the data is sent reliably, it's sent asynchronously, and it doesn't impact the loading of the next page. In addition, the code is actually simpler to write than any of these other techniques!

The following example shows a theoretical analytics code pattern that submits data to a server using the sendBeacon() method.

window.addEventListener("unload", logData, false);

function logData() {
  navigator.sendBeacon("/log", analyticsData);
}

The beacon sends an HTTP request with the POST method. As with XHR, the beacon request will be sent with all relevant cookies available at the time sendBeacon() is called.

Specifications

Browser compatibility

See also

• navigator