This is an experimental technology
Because this technology's specification has not stabilized, check the compatibility table for usage in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the specification changes.
The Beacon interface is used to schedule an asynchronous and non-blocking request to a web server. Beacon requests use the HTTP POST method and requests typically do not require a response. Requests are guaranteed to be initiated before a page is unloaded and they are run to completion without requiring a blocking request (for example XMLHttpRequest).
Example use cases of the Beacon API are logging activity and sending analytics data to the server.
Example code of the interfaces described in this document is included in Using the Beacon API.
Why use Beacon?
The Beacon interface addresses the needs of analytics and diagnostics code that typically attempts to send data to a web server before unloading 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.
User agents will typically ignore asynchronous XMLHttpRequests made in an unload handler. To solve this problem, analytics and diagnostics code will typically make a synchronous XMLHttpRequest in an unload or beforeunload handler to submit the data. The synchronous XMLHttpRequest forces the browser to delay unloading the document, and makes the next navigation appear to be slower. There is nothing the next page can do to avoid this perception of poor page load performance.
There are other techniques used to ensure that data is submitted. One such technique is to delay the unload to submit data by creating an Image 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 also result in the perception of poor page load performance for the next navigation. The Beacon API provides a standard way to address these issues.
Global context
The Beacon API's Navigator.sendBeacon() method is used to send a beacon of data to the server in the global browsing context. The method takes two arguments, the URL and the data to send in the request. The data argument is optional and its type may be an ArrayBufferView, Blob, DOMString, or FormData. If the browser successfully queues the request for delivery, the method returns "true" and returns "false" otherwise.
Worker context
The Beacon API's WorkerNavigator.sendBeacon() method is used to send a beacon of data to the the server from the worker global scope. The method takes two arguments, the URL and the data to send in the request. The data argument is optional and its type may be an ArrayBufferView, Blob, DOMString, or FormData. If the browser successfully queues the request for delivery, the method returns "true" and returns "false" otherwise.
Browser compatibility
The Navigator.sendBeacon().#Browser_compatibility table indicates that method has relatively broad implementation. However, the WorkerNavigator.sendBeacon().#Browser_compatibility data shows that method has no implementation.
To test your browser's support for this API, run the perf-api-support application.
See also
WorkerGlobalScope- Beacon standard
- Beacon CanIUse data
- Intercepting beacons through service workers; Ehsan Akhgari; 2015-Apr-08