Beacon

Abstract

This specification defines an interoperable means for site developers to asynchronously transfer small HTTP data from the User Agent to a web 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 specification as a Last Call Working Draft 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.

The deadline for review is 29 July 2014.

Publication as a 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 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 to a web server.

The specification addresses the needs of analytics and diagnostics code 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 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 in order 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.

window.addEventListener('unload', logData, false);

function logData() {
    var client = new XMLHttpRequest();
    client.open("POST", "/log", false); // third parameter indicates sync xhr
    client.setRequestHeader("Content-Type", "text/plain;charset=UTF-8");
    client.send(analyticsData);
}

Using the sendBeacon method, the data will be transmitted asynchronously to the web server when the User Agent has had an opportunity to do so, without delaying the unload or affecting the performance of the next navigation.

window.addEventListener('unload', logData, false);

function logData() {
    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 to a web server.

4.2 sendBeacon Method

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

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

The sendBeacon method transmits data provided by the data parameter to the URL provided by the url parameter. User agents MUST honor the HTTP headers (including, in particular, redirects and 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 at the earliest available opportunity, but MAY prioritize the transmission of data lower compared to other network traffic. The User Agent SHOULD make a best effort attempt to eventually transmit the data.

4.3 Processing Model

On calling the sendBeacon method, the following steps must be run:

1. Set requestTime to current time.

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

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

4. Set referrer to the entry setting object's API referrer source's URL if entry setting object's API referrer source is a document, and entry setting object's API referrer source otherwise

5. Set parsedUrl 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 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 and set the return value to false.

7. Otherwise, create the following temporary variables and then follow the rules below: let encoding be null, 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 mimeType be its value.

   Let transmittedData be the raw data represented by data.

   If data is a string

   Let encoding be UTF-8.

   Let 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 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 mimeType is not null, append a Content-Type header with value mimeType to headerList. Append a Accept-Language header with an appropriate value to headerList. Append a Accept header with */* as the value to headerList.

9. Set the 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

    url

    parsedUrl

    header list

    headerList

    origin

    origin

    force Origin header flag

    Set.

    context

    ping.

    referrer

    referrer

    body

    transmittedData

    mode

    CORS

    credentials mode

    omit

11. Set age to current time minus 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 2014. This version of the CORS specification is available from http://www.w3.org/TR/cors/.

[DOM]

W3C DOM4, Anne van Kesteren, et al, Editors. World Wide Web Consortium, 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, June 2014. This version of the HTML5 is available from http://www.w3.org/TR/html5/. The latest editor's draft of 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, et al, Editors. World Wide Web Consortium, 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

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.