Abstract

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 currentW3C publications and the latest revision of this technical report can be found in theW3C technical reports index at https://www.w3.org/TR/.

This document was published by theWeb Performance Working Group as a Candidate Recommendation Draft using theRecommendation track.

Publication as a Candidate Recommendation does not imply endorsement byW3C 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 theW3C Patent Policy.W3C maintains apublic 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 containsEssential Claim(s) must disclose the information in accordance withsection 6 of theW3C Patent Policy.

This document is governed by the2 November 2021W3C Process Document.

This section is non-normative.

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 thesendBeacon() 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>

The requests initiated via thesendBeacon() 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.

WhatsendBeacon() does not do and is not intended to solve:

• ThesendBeacon() 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.
• ThesendBeacon() 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.
• ThesendBeacon() method does not provide ability to customize the request method, provide custom request headers, or change otherprocessing properties of the request and response. Applications that require non-default settings for such requests should use the [FETCH] API withkeepalive set totrue.

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 wordsMAY,MUST,SHOULD, andSHOULD NOT in this document are to be interpreted as described inBCP 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.)

ThesendBeacon() 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 bysendBeacon() is subject to following properties:

• If the request does not contain a payload, or the requestContent-Type is aCORS-safelisted request-header, then the request mode isno-cors—similar to an image beacon or form-post respectively.
• Otherwise, a CORS preflight is made and the server needs to first allow such requests by returning the appropriate set of CORS headers:Access-Control-Allow-Credentials,Access-Control-Allow-Origin,Access-Control-Allow-Headers.

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, thesendBeacon() API does apply two restrictions: there is no callback method, and the payload size can be restricted by the user agent. Otherwise, thesendBeacon() API is not subject to any additional restrictions. The user agent ought not skip or throttle processing ofsendBeacon() calls, as they can contain critical application state, events, and analytics data. Similarly, the user agent ought not disablesendBeacon() when in "private browsing" or equivalent mode, both to avoid breaking the application and to avoid leaking that the user is in such mode.

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.