Copyright
©
2013
2014
W3C
®
(
MIT
,
ERCIM
,
Keio
,
Beihang
),
All
Rights
Reserved.
W3C
liability
,
trademark
and
document
use
rules
apply.
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.
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 .
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.
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 xhrclient.open("POST", "/log", false); // third parameter indicates sync xhr client.setRequestHeader("Content-Type", "text/plain;charset=UTF-8"); client.send(analyticsData); }
Using
the
method,
the
data
will
be
transmitted
asynchronously
to
the
web
server
when
the
beacon
sendBeacon
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.
The
following
example
shows
a
theoretical
analytics
code
pattern
that
submits
data
to
a
server
using
the
by
using
the
method.
beacon
sendBeacon
window.addEventListener('unload', logData, false); function logData() {return beacon("POST", "/log", analyticsData);navigator.sendBeacon("/log", analyticsData); }
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]
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]
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.
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
method
beacon
sendBeacon
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.
url
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
The
data
parameter
is
the
ArrayBufferView
,
Blob
,
Document
,
DOMString,
or
FormData
data
that
is
to
be
transmitted.
On
calling
the
beacon
The
sendBeacon
method,
the
following
steps
must
be
run:
Let
method
returns
true
if
the
user
agent
is
able
to
successfully
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.
Let
base
be
null.
data
for
transfer.
Otherwise
it
returns
false.
If
the
JavaScript
global
environment
is
a
document
environment
,
run
these
steps:
If
document
is
not
fully
active
,
throw
an
"
InvalidStateError
"
exception
User
Agent
limits
the
amount
of
data
that
can
be
queued
to
be
sent
using
this
API
and
terminate
the
overall
set
size
of
steps.
Set
base
data
causes
that
limit
to
be
exceeded,
this
method
returns
false.
A
return
value
of
true
implies
the
document
base
URL
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.
The
actual
data
transfer
may
occur
after
the
page
has
unloaded.
To
be
still
an
effective
mechanism
for
developers,
the
User
Agent
should
make
the
best
effort
to
transmit
the
data
including
making
multiple
attempts
to
transmit
the
data
in
presence
of
document.
transient
network
or
server
errors,
even
though
it
uses
POST
to
transmit
the
data.
Set
source
origin
to
On
calling
the
origin
sendBeacon
of
document
otherwise.
method,
the
following
steps
must
be
run:
Set
referrer
source
requestTime
to
document.
current
time.
Set
base
to
the
script's
entry
setting
object's
API
base
URL
.
Set
source
origin
to
the
script
entry
setting
object's
's
origin
.
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
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.
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.
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.
ArrayBuffer
Let the transmittedData be the raw data represented by data .
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 .
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.
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
.
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
.
sendBeacon()
call,
but
continue
to
runs
the
following
steps.
These
steps
may
be
run
even
after
the
document
has
unloaded.
Let req be a new request , initialized as follows:
POST
HTTP
method
Origin
header
flag
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
.
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.