W3C

Beacon

W3C First Public Working Draft 29 October 2013

This version:
http://www.w3.org/TR/2013/WD-beacon-20131029/
Latest published version:
http://www.w3.org/TR/beacon/
Latest Editor's Draft:
http://dvcs.w3.org/hg/webperf/raw-file/tip/specs/Beacon/Overview.html
Editors:
Jatinder Mann, Microsoft Corp., <>
Alois Reitbauer, Compuware Corp., <>

Copyright © 2013 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.

Abstract

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

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 Working Draft for the Beacon specification.

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

This document is produced by the Web Performance Working Group.

Publication as a First Public 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 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 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 data from the user agent to a web server, with the user agent taking the responsibility to eventually send the data.

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 data has been submitted can result in improved battery life.

Additionally, analytics and diagnostics code will 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 little the next page can do to avoid this perception of poor page load performance.

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

The following example shows a theoretical analytics code that attempts to submit data to a server by using a synchronous XMLHttpRequest in an unload handler. This results in the unload of the page to be delayed. 

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

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

Using the beacon 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. 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.

The following example shows a theoretical analytics code that submits data to a server using the by using the beacon method. 

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

function logData() {
    return beacon("POST", "/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 data from the user agent to a web server, with the user agent taking the responsibility to eventually send the data.

4.2 beacon Method

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

partial interface Window {
void beacon(BeaconHTTPMethod method, DOMString url, (ArrayBufferView or Blob or Document or DOMString or FormData)? data);
};

The beacon 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 data transfer may occur after the page has unloaded. Developers should assume that any data transmitted using this method will eventually be sent.

method parameter

The method parameter indicates the desired HTTP method used to transmit the data. The user agent may throw the SyntaxError exception if the method parameter is not one of the following DOMStrings: POST, PUT, and GET.

Note

As this interface can only be used to transmit data, only the POST, PUT, GET HTTP methods are supported by this interface.

Throwing the SyntaxError exception for a unsupported method of transmission may not always be possible, as the user agent may not yet have received the Access-Control-Allow-Methods CORS header.

url parameter

The url parameter indicates the resolved URL where the data is to be transmitted. The user agent must throw the SyntaxError exception if the URL cannot be resolved.

data parameter

The data parameter is the ArrayBufferView, Blob, Document, DOMString, or FormData data that is to be transmitted.

4.3 Processing Model

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

  1. Let the user agent queue an asynchronous task that runs the following steps. These steps may be run even after the document has unloaded. Return control flow back to script.

  2. Let base be null.

  3. If the JavaScript global environment is a document environment, run these steps:

    1. If document is not fully active, throw an "InvalidStateError" exception and terminate the overall set of steps.

    2. Set base to the document base URL of document.

    3. Set source origin to the origin of document otherwise.

    4. Set referrer source to document.

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

    1. Set base to the script's base URL.

    2. Set source origin to the script's origin.

    3. Set referrer source to the script's referrer source.

  5. If method does not match the POST, PUT, or GET Method token, throw a "SyntaxError" exception and terminate these steps.

  6. Let url be a URL with character encoding UTF-8.

  7. Resolve url relative to base. If the algorithm returns an error, throw a "SyntaxError" exception and terminate these steps.

  8. If data is null, throw a "SyntaxError" exception and terminate these steps.

  9. Otherwise, create the following temporary variable and then follow the rules below: let encoding be null, mime type 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 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 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 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.

  10. If URL is of the same origin as base, fetch URL from the base origin using the method HTTP method with transmittedData, encoding, and mime type.

    Otherwise, make a cross-origin request to URL, using the method HTTP method with transmittedData, encoding, and mime type.

6 References

[CORS]
Cross-Origin Resource Sharing, Anne van Kesteren, Editor. World Wide Web Consortium, January 2013. This version of the CORS specification is available from http://www.w3.org/TR/cors/.
[DOM]
DOM4, Anne van Kesteren, Editor. World Wide Web Consortium, December 2012. This version of the DOM4 specification is available from http://www.w3.org/TR/dom/.
[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. 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. World Wide Web Consortium, December 2012. 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