2.1 Dependencies

DOM

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

• the document URL
• document
• throw a name exception
• the SyntaxError error name

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 value
• request
• request method
• request url
• request header list
• request origin
• request force Origin header flag
• request context
• 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

XMLHttpRequest

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

• FormData interface

3.2 sendBeacon Method

partial interface Navigator {
    boolean sendBeacon(USVString url, optional BodyInit? data = null);
};
partial interface WorkerNavigator {
    boolean sendBeacon(USVString url, optional BodyInit? data = null);
};

The sendBeacon method transmits data provided by the data parameter to the URL provided by the url parameter. User agents 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.

3.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 settings object's API base URL.

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

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

5. 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 "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:
   • Extract object's byte stream (transmittedData) and MIME type (mimeType).
   • Let headerList be null.

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

    url

    parsedUrl

    header list

    headerList

    origin

    origin

    force Origin header flag

    set

    context

    beacon

    referrer

    referrer

    body

    transmittedData

    mode

    CORS

    credentials mode

    include

11. Set age to current time minus requestTime expressed in seconds. If age is non-zero, append a Beacon-Age header with value age to header list field of req.

12. Fetch req.

The Beacon-Age header field is used to communicate the time delay, measured in seconds, between the time when the request is sent and the requestTime set when sendBeacon method is called. The ABNF (Augmented Backus-Naur Form) syntax for the Beacon-Age header field is as follows:

Beacon-Age = "Beacon-Age" ":" 1*DIGIT

3.5 IANA Considerations

The permanent message header field registry should be updated with the following registrations ([RFC3864]):