This specification defines an interface that web developers can use to
schedule asynchronous and non-blocking delivery of data that minimizes
resource contention with other time-critical operations, while ensuring
that such requests are still processed and delivered to destination.
Status of This Document
This section describes the status of this
document at the time of its publication. A list of current W3C
publications and the latest revision of this technical report can be found
in the W3C technical reports index at
https://www.w3.org/TR/.
Publication as a Candidate Recommendation does not
imply endorsement by W3C and its Members. A Candidate Recommendation Draft integrates
changes from the previous Candidate Recommendation that the Working Group
intends to include in a subsequent Candidate Recommendation Snapshot.
This is a draft document and may be updated, replaced or obsoleted by other
documents at any time. It is inappropriate to cite this document as other
than work in progress.
This document was produced by a group
operating under the
W3C Patent
Policy.
W3C maintains a
public list of any patent disclosures
made in connection with the deliverables of
the group; that page also includes
instructions for disclosing a patent. An individual who has actual
knowledge of a patent which the individual believes contains
Essential Claim(s)
must disclose the information in accordance with
section 6 of the W3C Patent Policy.
Web applications often need to issue requests that report events, state
updates, and analytics to one or more servers. Such requests typically do
not require response processing on the client (e.g. result in 204, or 200
HTTP response codes with an empty response body), and should not compete
for network and compute resources with other high priority operations such
as fetching critical resources, reacting to input, running animations, and
so on. However, such one-way requests (beacons), are also responsible for
delivering critical application and measurement data, forcing developers to
use costly methods to ensure their delivery:
Developers opt for immediate delivery of each beacon, instead of
coalescing and deferring their delivery because this provides improved
delivery rates. Deferring delivery may mean that the beacon request may
not have sufficient time to complete successfully, which leads to loss of
important application data.
Developers opt for issuing blocking requests via synchronous
XMLHttpRequest's, inserting no-op busy loops, or using other techniques
that block the user agent from executing time-critical operations (e.g.
click, unload, and other handlers) and hurt the user experience. The
blocking behavior is used to provide improved delivery rate, as it
prevents the user agent and the operating system from cancelling the
request if the page is unloaded, suspended, or killed by the system.
The mismatch between above delivery and processing requirements leaves
most developers with a tough choice and widespread adoption of blocking
techniques that hurt the user experience. This specification defines an
interface that web developers can use to schedule asynchronous and
non-blocking delivery of data that minimizes resource contention with other
time-critical operations, while ensuring that such requests are still
processed and delivered to destination:
Beacon requests are prioritized to avoid competing with time-critical
operations and higher priority network requests.
Beacon requests may be efficiently coalesced by the user agent to
optimize energy use on mobile devices.
Beacon requests are guaranteed to be initiated before page is
unloaded and are allowed to run to completion without requiring blocking
requests or other techniques that block processing of user interactive
events.
The following example shows use of the sendBeacon() method to
deliver event, click, and analytics data:
<html><script>// emit non-blocking beacon to record client-side eventfunctionreportEvent(event) {
var data = JSON.stringify({
event: event,
time: performance.now()
});
navigator.sendBeacon('/collector', data);
}
// emit non-blocking beacon with session analytics as the page// transitions to background state (Page Visibility API)document.addEventListener('visibilitychange', function() {
if (document.visibilityState === 'hidden') {
var sessionData = buildSessionReport();
navigator.sendBeacon('/collector', sessionData);
}
});
</script><body><ahref='http://www.w3.org/'onclick='reportEvent(this)'><buttononclick="reportEvent('some event')">Click me</button></body></html>
Note
Above example uses visibilitychange
event defined in [PAGE-VISIBILITY-2] to trigger delivery of session data.
This event is the only event that is guaranteed to fire on mobile devices
when the page transitions to background state (e.g. when user switches to a
different application, goes to homescreen, etc), or is being unloaded.
Developers should avoid relying on unload event because it will
not fire whenever a page is in a background state (i.e.
visibilityState equal to hidden and the process is
terminated by the mobile OS.
The requests initiated via the sendBeacon() method do not block
or compete with time-critical work, may be prioritized by the user agent to
improve network efficiency, and eliminate the need to use blocking
operations to ensure delivery of beacon data.
What sendBeacon() does not do and is not intended to solve:
The sendBeacon() method does not provide special handling for
offline storage or delivery. A beacon request is like any other request
and may be combined with [SERVICE-WORKERS] to provide offline
functionality where necessary.
The sendBeacon() method is not intended to provide background
synchronization or transfer capabilities. The user agent restricts the
maximum accepted payload size to ensure that beacon requests are able to
complete quickly and in a timely manner.
The sendBeacon() method does not provide ability to customize
the request method, provide custom request headers, or change other
processing properties of the request
and response. Applications that require non-default settings for such
requests should use the [FETCH] API with keepalive set to
true.
2. Conformance
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, SHOULD, and SHOULD NOT in this document
are to be interpreted as described in
BCP 14
[RFC2119] [RFC8174]
when, and only when, they appear in all capitals, as shown here.
For readability, these words do not appear in all uppercase letters in
this specification.
Requirements phrased in the imperative as part of algorithms (such as
"strip any leading space characters" or "return false and abort these
steps") are to be interpreted with the meaning of the key word ("must",
"should", "may", etc) used in introducing the algorithm.
Some conformance requirements are phrased as requirements on attributes,
methods or objects. Such requirements are to be interpreted as requirements
on the user agent.
Conformance requirements phrased as algorithms or specific steps may be
implemented in any manner, so long as the end result is equivalent. (In
particular, the algorithms defined in this specification are intended to be
easy to follow, and not intended to be performant.)
The sendBeacon() method transmits data provided by the
data parameter to the URL provided by the url parameter:
The user agent MUST initiate a fetch with keepalive
flag set, which restricts the amount of data that can be queued by such
requests to ensure that beacon requests are able to complete quickly and
in a timely manner.
The user agent MUST schedule immediate transmission of all beacon
requests when the document visibilityState transitions to
hidden, and must allow all such requests to run to
completion without blocking other time-critical and high-priority work.
The user agent SHOULD schedule transmission of provided data to
minimize resource (CPU and network) contention with other time-critical
and high priority work.
The user agent MAY delay transmission of provided data to optimize
network and energy efficiency - e.g. deliver immediately if the network
is active, or wait until network interface is active. However, the user
agent SHOULD NOT delay transmission indefinitely and ensure that
pending transmissions are periodically flushed even if there is no
other network activity.
Note
Beacon API does not provide a response callback. The server is
encouraged to omit returning a response body for such requests (e.g.
respond with 204 No Content).
Parameters
url
The url parameter
indicates the URL where the data is to be transmitted.
data
The data parameter is the BodyInit data
that is to be transmitted.
Return Value
The sendBeacon() method returns true if the user agent is
able to successfully queue the data for transfer. Otherwise it returns
false.
Note
The user agent imposes limits on the amount of data
that can be sent via this API: this helps ensure that such requests are
delivered successfully and with minimal impact on other user and
browser activity. If the amount of data to be queued exceeds
the user agent limit (as defined in HTTP-network-or-cache
fetch), this method returns false; a return value of
true implies the browser has queued the data for transfer.
However, since the actual data transfer happens asynchronously, this
method does not provide any information whether the data transfer has
succeeded or not.
3.2 Processing Model
On calling the sendBeacon() method with url and
optional data, the following steps must be run:
Set parsedUrl to the result of the URL parser
steps with url and base. If the algorithm
returns an error, or if parsedUrl's scheme is not
"http" or "https", throw a
"TypeError" exception and terminate these
steps.
Let headerList be an empty list.
Let corsMode be "no-cors".
If data is not null:
Set transmittedData and contentType to the
result of extractingdata's
byte stream with the keepalive flag set.
If the amount of data that can be queued to be sent by
keepalive enabled requests is exceeded by the size of
transmittedData (as defined in HTTP-network-or-cache
fetch), set the return value to false and
terminate these steps.
Note
Requests initiated via the Beacon API automatically
set the keepalive flag, and developers can similarly
set the same flag manually when using the Fetch API. All requests
with this flag set share the same in-flight quota restrictions
that is enforced within the Fetch API.
The sendBeacon() interface provides an asynchronous and
non-blocking mechanism for delivery of data. This API can be used to:
Report client-side events to the server. The delivery is prioritized
and scheduled by the user agent such that it does not block other
interactive work and makes efficient use of system resources.
Report session data when the page transitions to background state or
is being unloaded, without blocking the user agent.
Other use cases that require delivery of small payloads and do not
expect a response callback.
The delivered data might contain potentially sensitive information, for
example, data about a user's activity on a web page, to a server. While
this can have privacy implications for the user, existing methods, such as
scripted form-submit, image beacons, and XHR/fetch requests provide similar
capabilities, but come with various and costly performance tradeoffs: the
requests can be aborted by the user agent unless the developer blocks the
user agent from processing other events (e.g. by invoking a synchronous
request, or spinning in an empty loop), and the user agent is unable to
prioritize and coalesce such requests to optimize use of system
resources.
A request initiated by sendBeacon() is subject to following
properties:
If the request does not contain a payload, or the request
Content-Type is a CORS-safelisted request-header,
then the request mode is no-cors—similar to an image beacon or
form-post respectively.
As such, from the security perspective, the Beacon API is subject to
same security policies as the current methods in use by developers.
Similarly, from the privacy perspective, the resulting requests are
initiated immediately when the API is called, or upon a page visibility
change, which restricts the exposed information (e.g. user's IP address) to
existing lifecycle events accessible to the developers. However, user
agents might consider alternative methods to surface such requests to
provide transparency to users.
Compared to the alternatives, the sendBeacon() API does apply two
restrictions: there is no callback method, and the payload size can be
restricted by the user agent. Otherwise, the sendBeacon() API is not
subject to any additional restrictions. The user agent ought not skip or
throttle processing of sendBeacon() calls, as they can contain
critical application state, events, and analytics data. Similarly, the user
agent ought not disable sendBeacon() when in "private browsing" or
equivalent mode, both to avoid breaking the application and to avoid
leaking that the user is in such mode.
A. Acknowledgments
Thanks to Alois Reitbauer, Arvind Jain, Anne van Kesteren, Boris
Zbarsky, Chase Douglas, Daniel Austin, Jatinder Mann, James Simonsen, Jason
Weber, Jonas Sicking, Nick Doty, Philippe Le Hegaret, Todd Reifsteck, Tony
Gentilcore, William Chan, and Yoav Weiss for their contributions to this
work.
