Beacon

Abstract

This specification defines an interoperable means for site developers to asynchronously transfer small HTTP data from the user agent User Agent to a web server, with the user agent taking the responsibility to eventually send the data. server.

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 http://www.w3.org/TR/.

This is the First Public specification as a Last Call Working Draft for the Beacon specification. and is intended to become a W3C Recommendation.

Please send comments to public-web-perf@w3.org ( archived ) with [Beacon] at the start of the subject line.

This document The deadline for review is produced by the Web Performance Working Group . 29 July 2014 .

Publication as a First Public Last Call Working Draft 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 is a Last Call Working Draft and thus the Working Group has determined that this document has satisfied the relevant technical requirements and is interested in getting wide review.

A list of changes is available.

This document is produced by the Web Performance Working Group.

This document was produced by a group operating under the 5 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 contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy .

Table of Contents

1. 1 Introduction
2. 2 Conformance requirements
3. 3 Terminology
4. 4 Beacon
   1. 4.1 Introduction
   2. 4.2 beacon sendBeacon Method
   3. 4.3 Processing Model
5. 6 References
6. Acknowledgements

1 Introduction

This section is non-normative.

The Beacon specification defines an interface that web developers can use to asynchronously transfer small HTTP data from the user agent User Agent to a web server, with the user agent taking the responsibility to eventually send the data. server.

This method can be used at any time to asynchronously transfer data to a web server, without the need to check whether the data transfer has succeeded or not. On a mobile website, batching multiple beacons at the same time and not having to check whether The specification addresses the data has been submitted can result in improved battery life. Additionally, needs of analytics and diagnostics code will that typically attempt 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.

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 user agent User Agent to delay unloading the document, and makes the next navigation appear to be slower. There is little nothing the next page can do to avoid this perception of poor page load performance.

In addition, there There are other poor patterns techniques used to ensure that data is submitted. One such pattern technique is to delay the unload in order to submit data is to create by creating an Image element and set 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.

window.addEventListener('unload', logData, false);
function logData() {
    var client = new XMLHttpRequest();
    client.open("POST", "/log", false); // third paramater indicates sync xhr

    client.open("POST", "/log", false); // third parameter indicates sync xhr

    client.setRequestHeader("Content-Type", "text/plain;charset=UTF-8");
    client.send(analyticsData);
}

Using the beacon sendBeacon method, the data will be transmitted asynchronously to the web server when the user agent User Agent has had an opportunity to do so, without delaying the unload or affecting the performance of the next navigation. As the user agent takes the responsibility to transmit the data, the beacon method does not provide any return values indicating whether or not the transfer has succeeded.

window.addEventListener('unload', logData, false);
function logData() {
    return beacon("POST", "/log", analyticsData);

    navigator.sendBeacon("/log", analyticsData);

}

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 RFC 2119 . 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 user agents.

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 IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [Web IDL]

3 Terminology

The construction "a Foo object", where Foo is actually an interface, is sometimes used instead of the more accurate "an object implementing the interface Foo ".

The terms origin and same origin are defined by The HTTP Origin Header. [IETF RFC 6454]

4 Beacon

4.1 Introduction

This section is non-normative.

This specification defines an interoperable means for site developers to asynchronously transfer small HTTP data from the user agent User Agent to a web server, with the user agent taking the responsibility to eventually send the data. server.

4.2 beacon sendBeacon Method

enum  { "POST", "PUT", "GET" };

partial interface Navigator {
    boolean sendBeacon(DOMString url, optional (ArrayBufferView or Blob or DOMString or FormData)? data = null);
};

partial interface  {
void );

partial interface WorkerNavigator {
    boolean sendBeacon(DOMString url, optional (ArrayBufferView or Blob or DOMString or FormData)? data = null);

};

The beacon sendBeacon method does not provide a return value indicating whether the data transfer has succeeded. Note This method does not provide any information whether the data transfer has succeeded or not, as the transmits data transfer may occur after provided by the page has unloaded. Developers should assume that any data transmitted using this method will eventually be sent. method parameter The method data parameter indicates the desired HTTP method used parameter to transmit the data. The user agent may throw the SyntaxError exception if URL provided by the method url parameter is not one of parameter. User agents MUST honor the following DOMStrings: POST , PUT , HTTP headers (including, in particular, redirects and GET . Note As this interface can only be used to HTTP cookie headers), but MUST ignore any entity bodies returned in the response. User agents MAY close the connection prematurely once they start receiving an entity body. The User Agent SHOULD transmit data, only data at the POST , PUT , GET HTTP methods are supported by this interface. Throwing earliest available opportunity, but MAY prioritize the SyntaxError exception for a unsupported method of transmission may not always be possible, as the user agent may not yet have received of data lower compared to other network traffic. The User Agent SHOULD make a best effort attempt to eventually transmit the Access-Control-Allow-Methods CORS header. data.

4.3 Processing Model

Set source origin to On calling the origin sendBeacon of document otherwise. method, the following steps must be run:

1. Set referrer source requestTime to document. current time.

   If the JavaScript global environment is a worker environment , run these steps:

2. Set base to the script's entry setting object's API base URL .

3. Set source origin to the script entry setting object's 's origin .

4. Set referrer source to the script's entry setting object's API referrer source . If method does not match the POST , PUT , or GET Method token, throw 's URL a " SyntaxError if entry setting object's " exception and terminate these steps. Let url be API referrer source is a URL document , and entry setting object's with character encoding UTF-8. API referrer source otherwise

5. Resolve url Set parsedUrl relative to the result of parsing url with base . If the algorithm returns an error, or if parsedUrl 's scheme is not "http" or "https", throw a " SyntaxError " exception and terminate these steps.

6. If data is null, throw a " SyntaxError " exception not null and if the user agent limits the amount of data that can be queued to be sent using this API and the size of data causes that limit to be exceeded, terminate these steps. steps and set the return value to false.

7. Otherwise, create the following temporary variable variables and then follow the rules below: let encoding be null, mime type mimeType be null, headerList be null, and transmittedData be null.

   If data is a ArrayBuffer

   Let the transmittedData be the raw data represented by data .

   If data is a Blob

   If the object's type attribute is not the empty string let mime type mimeType be its value.

   Let transmittedData be the raw data represented by data .

   If data is a Document Let encoding be the preferred MIME name of the character encoding of data . If encoding is UTF-16 change it to UTF-8. Let mime type be " application/xml " or " text/html " if Document is an HTML document , followed by " ;charset= ", followed by encoding . Let the transmittedData be the result of getting the innerHTML attribute on data converted to Unicode and encoded as encoding . Re-throw any exception this throws. In particular, if the document cannot be serialized an " InvalidStateError " exception is thrown. Subsequent changes to the Document have no effect on what is transferred. If data is a string

   Let encoding be UTF-8.

   Let mime type mimeType be " text/plain;charset=UTF-8 ".

   Let the transmittedData be data converted to Unicode and encoded as UTF-8.

   If data is a FormData

   Let transmittedData be the result of running the multipart/form-data encoding algorithm with data as form data set and with UTF-8 as the explicit character encoding.

   Let mime type mimeType be the concatenation of " multipart/form-data; ", a U+0020 SPACE character, " boundary= ", and the multipart/form-data boundary string generated by the multipart/form-data encoding algorithm .

8. If URL mimeType is of the same origin as not null, append a Content-Type header with value base , fetch mimeType to headerList . Append a Accept-Language header with an appropriate value to URL from headerList . Append a Accept header with */* as the value to base origin using headerList .

9. Set the method return value to true and return the sendBeacon() call, but continue to runs the following steps. These steps may be run even after the document has unloaded.

10. Let req be a new request , initialized as follows:

    method

    POST HTTP method with transmittedData ,

    url

    encoding , and parsedUrl

    header list

    mime type . Otherwise, make a cross-origin request headerList

    origin to

    URL , using the origin

    force Origin header flag

    Set.

    context

    ping .

    referrer

    method referrer HTTP method

    body with

    transmittedData ,

    mode

    CORS

    credentials mode

    omit

11. Set encoding , and age to current time minus mime type requestTime expressed in seconds. Append a Beacon-Age header with value age to header list field of req . Fetch req .

6 References

[CORS]

Cross-Origin Resource Sharing , Anne van Kesteren, Editor. W3C Recommendation, World Wide Web Consortium, January 2013. 2014. This version of the CORS specification is available from http://www.w3.org/TR/cors/.

[DOM]

W3C DOM4 , Anne van Kesteren, Editor. et al, Editors. World Wide Web Consortium, December 2012. May 2014. This version of the W3C DOM4 specification is available from http://www.w3.org/TR/dom/.

[Fetch]

Fetch , Anne van Kesteren, Editor. Living Standard, WHATWG. This version of the Fetch specification is available from http://fetch.spec.whatwg.org/.

[IETF RFC 2119]

Key words for use in RFCs to Indicate Requirement Levels , Scott Bradner, Author. Internet Engineering Task Force, March 1997. Available at http://www.ietf.org/rfc/rfc2119.txt .

[ IETF RFC 6454 ]

The Web Origin Concept , Adam Barth, Author. Internet Engineering Task Force, December 2011. Available at http://www.ietf.org/rfc/rfc6454.txt .

[HTML5]

HTML5 , Robin Berjon, et al, Editors. World Wide Web Consortium, August 2013. June 2014. This version of the HTML5 is available from http://www.w3.org/TR/html5/ . The latest editor's draft of the HTML is available from latest editor's draft is available at http://www.w3.org/html/wg/drafts/html/master/.

[ XMLHttpRequest ]

XMLHttpRequest , Anne van Kesteren, Author. et al, Editors. World Wide Web Consortium, December 2012. January 2014. This version of the XMLHttpRequest specification is http://www.w3.org/TR/XMLHttpRequest/. The latest version of XMLHttpRequest is available at http://www.w3.org/TR/XMLHttpRequest/.

[ Web IDL ]

Web IDL , Cameron McCormack, Editor. World Wide Web Consortium, April 2012. This version of the Web IDL specification is available from http://www.w3.org/TR/2012/CR-WebIDL-20120419/. The latest version of Web IDL is available at http://www.w3.org/TR/WebIDL/.

[TYPEDARRAY]

Typed Array , David Herman and Kenneth Russell. Khronos.

Acknowledgements

TBD We would like to sincerely thank Jonas Sicking, Ilya Grigorik, James Simonsen, William Chan, Jason Weber, Philippe Le Hegaret, Daniel Austin, Chase Douglas, and others who have helped refine this specification to acknowledge their contributions to this work.