Beacon (original) (raw)

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. Other documents may supersede this document. 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/.

This document was published by the Web Performance Working Group as a Candidate Recommendation. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please file an issue or send them topublic-web-perf@w3.org (subscribe,archives).W3C publishes a Candidate Recommendation to indicate that the document is believed to be stable and to encourage implementation by the developer community. This Candidate Recommendation is expected to advance to Proposed Recommendation no earlier than 11 May 2017. All comments are welcome.

The Working Group expects to demonstrate 2 implementations of the features listed in this specification by the end of the Candidate Recommendation phase. Please see the Working Group's implementation report.

Publication as a Candidate Recommendation does not imply endorsement by the W3C Membership. 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 the5 February 2004 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 containsEssential Claim(s) must disclose the information in accordance withsection 6 of the W3C Patent Policy.

This document is governed by the 1 March 2017 W3C Process Document.

Table of Contents

1. 1. Introduction
2. 2. Conformance requirements
   1. 2.1 Dependencies
3. 3. Beacon
   1. 3.1 sendBeacon Method
   2. 3.2 Processing Model
   3. 3.3 Privacy and Security
   4. 3.4 Acknowledgments
4. A. References
   1. A.1 Normative references
   2. A.2 Informative references

1. Introduction

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 the sendBeacon method to deliver event, click, and analytics data:

Example 1

Note

Above example uses visibilitychange event defined in [PAGE-VISIBILITY] 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 in background state (i.e.visiblityState 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 withkeepalive flag set totrue.

2. Conformance requirements

All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in [RFC2119]. 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.)

2.1 Dependencies

DOM

The following terms are defined in the DOM specification: [DOM]

• the document URL
• document
• throw a name exception

HTML5

The following terms are defined in the HTML specification: [HTML5]

• API base URL
• API referrer source
• entry settings object
• multipart/form-data boundary string
• multipart/form-data encoding algorithm
• resource origin

Fetch

The following terms are defined in the HTML specification: [FETCH]

• header
• request
• request method
• request url
• request header list
• request origin
• request keep-alive flag
• request referrer
• request body
• request mode
• request credentials mode
• fetch
• BodyInit

File API

The following terms are defined in the File API specification: [FILEAPI]

• Blob interface
• the type attribute

Typed Array

The following terms are defined in the Typed Array specification: [TYPEDARRAY]

• ArrayBufferView interface
• ArrayBuffer interface

URL

The following terms are defined in the URL specification: [URL]

• URL parser
• scheme

Web IDL

The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification [WebIDL].

The following terms are defined in the Web IDL specification:

• USVString type
• TypeError type

XMLHttpRequest

The following term is defined in the XMLHttpRequest specification: [XMLHttpRequest]

• FormData interface

3.1 sendBeacon Method

The sendBeacon method transmits data provided by the data parameter to the URL provided by the url parameter:

• The user agent MUST restrict the maximum data size 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 visiblityState ([PAGE-VISIBILITY]) 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, 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 withurl and optional data, the following steps must be run:

1. Set base to the entry settings object's API base URL.
2. Set origin to the entry settings object'sorigin.
3. Set referrer to the entry settings object's'API referrer source's URL if entry settings object'sAPI referrer source is a document, and entry settings object's API referrer source otherwise
4. 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](#typeerror)" exception and terminate these steps.
5. If data is not null:
   • Extract object's byte stream (transmittedData) and MIME type (mimeType).
   • If the amount of data that can be queued to be sent bykeepalive enabled requests is exceeded by the size of transmittedData, set the return value to false and terminate these steps.
     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.
   • Let corsMode be "cors".
   • Let headerList be null.
6. If mimeType is not null:
   • If mimeType value is a CORS-safelisted request-header value for the Content-Type header, set corsMode to "no-cors".
   • Append a Content-Type header with valuemimeType to headerList.
7. Set the return value to true, return thesendBeacon call, and continue to run the following steps in parallel:
   1. Let req be a new request, initialized as follows:
      method
      POST
      url
      parsedUrl
      header list
      headerList
      origin
      referrer
      referrer
      keep-alive flag
      true
      body
      transmittedData
      mode
      corsMode
      credentials mode
      include
   2. Fetch req.

3.3 Privacy and Security

This section is non-normative.

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 payload is one of application/x-www-form-urlencoded, multipart/form-data, or text/plain, then the request is a simple request that does not require an additional CORS-preflight; same as scripted form-post or XHR/fetch.
• Otherwise, if the payload is a Blob and the resulting Content-Type is not a simple header, then 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); same as XHR/fetch.

As such, from the security perspective, the Beacon API is subject to all the 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 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.

3.4 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.

A. References

A.1 Normative references

[DOM]

DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/

[FETCH]

Fetch Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://fetch.spec.whatwg.org/

[FILEAPI]

File API. Arun Ranganathan; Jonas Sicking. W3C. 21 April 2015. W3C Working Draft. URL: https://www.w3.org/TR/FileAPI/

[HTML5]

HTML5. Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Theresa O'Connor; Silvia Pfeiffer. W3C. 28 October 2014. W3C Recommendation. URL: https://www.w3.org/TR/html5/

[PAGE-VISIBILITY]

Page Visibility (Second Edition). Jatinder Mann; Arvind Jain. W3C. 29 October 2013. W3C Recommendation. URL: https://www.w3.org/TR/page-visibility/

[RFC2119]

Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119

[TYPEDARRAY]

Typed Array Specification. David Herman; Kenneth Russell. Khronos. 26 June 2013. Khronos Working Draft. URL: https://www.khronos.org/registry/typedarray/specs/latest/

[URL]

URL Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://url.spec.whatwg.org/

[WebIDL]

Web IDL. Cameron McCormack; Boris Zbarsky; Tobie Langel. W3C. 15 December 2016. W3C Working Draft. URL: https://www.w3.org/TR/WebIDL-1/

[XMLHttpRequest]

XMLHttpRequest Level 1. Anne van Kesteren; Julian Aubourg; Jungkee Song; Hallvord Steen et al. W3C. 6 October 2016. W3C Note. URL: https://www.w3.org/TR/XMLHttpRequest/

A.2 Informative references

[SERVICE-WORKERS]

Service Workers 1. Alex Russell; Jungkee Song; Jake Archibald; Marijn Kruisselbrink. W3C. 11 October 2016. W3C Working Draft. URL: https://www.w3.org/TR/service-workers-1/

[WEBIDL]

Web IDL. Cameron McCormack; Boris Zbarsky; Tobie Langel. W3C. 15 December 2016. W3C Working Draft. URL: https://www.w3.org/TR/WebIDL-1/