This
specification
defines
an
interface
that
web
developers
can
use
to
schedule
asynchronous
and
non-blocking
delivery
of
data
that
minimizes
resource
contention
with
other
time-critical
operations,
while
ensuring
that
such
requests
are
still
processed
and
delivered
to
destination.
Status
of
This
Document
This
is
a
preview
Do
not
attempt
to
implement
this
version
of
the
specification.
Do
not
reference
this
version
as
authoritative
in
any
way.
Instead,
see
https://w3c.github.io/beacon/
for
the
Editor's
draft.
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
https://www.w3.org/TR/.
Publication
as
an
Editor's
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.
Web
applications
often
need
to
issue
requests
that
report
events,
state
updates,
and
analytics
to
one
or
more
servers.
Such
requests
typically
do
not
require
response
processing
on
the
client
(e.g.
result
in
204,
or
200
HTTP
response
codes
with
an
empty
response
body),
and
should
not
compete
for
network
and
compute
resources
with
other
high
priority
operations
such
as
fetching
critical
resources,
reacting
to
input,
running
animations,
and
so
on.
However,
such
one-way
requests
(beacons),
are
also
responsible
for
delivering
critical
application
and
measurement
data,
forcing
developers
to
use
costly
methods
to
ensure
their
delivery:
Developers
opt
for
immediate
delivery
of
each
beacon,
instead
of
coalescing
and
deferring
their
delivery
because
this
provides
improved
delivery
rates.
Deferring
delivery
may
mean
that
the
beacon
request
may
not
have
sufficient
time
to
complete
successfully,
which
leads
to
loss
of
important
application
data.
Developers
opt
for
issuing
blocking
requests
via
synchronous
XMLHttpRequest's,
inserting
no-op
busy
loops,
or
using
other
techniques
that
block
the
user
agent
from
executing
time-critical
operations
(e.g.
click,
unload,
and
other
handlers)
and
hurt
the
user
experience.
The
blocking
behavior
is
used
to
provide
improved
delivery
rate,
as
it
prevents
the
user
agent
and
the
operating
system
from
cancelling
the
request
if
the
page
is
unloaded,
suspended,
or
killed
by
the
system.
The
mismatch
between
above
delivery
and
processing
requirements
leaves
most
developers
with
a
tough
choice
and
widespread
adoption
of
blocking
techniques
that
hurt
the
user
experience.
This
specification
defines
an
interface
that
web
developers
can
use
to
schedule
asynchronous
and
non-blocking
delivery
of
data
that
minimizes
resource
contention
with
other
time-critical
operations,
while
ensuring
that
such
requests
are
still
processed
and
delivered
to
destination:
Beacon
requests
are
prioritized
to
avoid
competing
with
time-critical
operations
and
higher
priority
network
requests.
Beacon
requests
may
be
efficiently
coalesced
by
the
user
agent
to
optimize
energy
use
on
mobile
devices.
Beacon
requests
are
guaranteed
to
be
initiated
before
page
is
unloaded
and
are
allowed
to
run
to
completion
without
requiring
blocking
requests
or
other
techniques
that
block
processing
of
user
interactive
events.
The
following
example
shows
use
of
the
sendBeacon()
method
to
deliver
event,
click,
and
analytics
data:
<html><script>// emit non-blocking beacon to record client-side eventfunctionreportEvent(event) {
var data = JSON.stringify({
event: event,
time: performance.now()
});
navigator.sendBeacon('/collector', data);
}
// emit non-blocking beacon with session analytics as the page// transitions to background state (Page Visibility API)document.addEventListener('visibilitychange', function() {
if (document.visibilityState === 'hidden') {
var sessionData = buildSessionReport();
navigator.sendBeacon('/collector', sessionData);
}
});
</script><body><ahref='http://www.w3.org/'onclick='reportEvent(this)'><buttononclick="reportEvent('some event')">Click me</button></body>
</
html
>
Note
Above
example
uses
visibilitychange
event
defined
in
[
PAGE-VISIBILITY-2
]
to
trigger
delivery
of
session
data.
This
event
is
the
only
event
that
is
guaranteed
to
fire
on
mobile
devices
when
the
page
transitions
to
background
state
(e.g.
when
user
switches
to
a
different
application,
goes
to
homescreen,
etc),
or
is
being
unloaded.
Developers
should
avoid
relying
on
unload
event
because
it
will
not
fire
whenever
a
page
is
in
a
background
state
(i.e.
visibilityState
equal
to
hidden
)
and
the
process
is
terminated
by
the
mobile
OS.
The
requests
initiated
via
the
sendBeacon()
method
do
not
block
or
compete
with
time-critical
work,
may
be
prioritized
by
the
user
agent
to
improve
network
efficiency,
and
eliminate
the
need
to
use
blocking
operations
to
ensure
delivery
of
beacon
data.
What
sendBeacon()
does
not
do
and
is
not
intended
to
solve:
The
sendBeacon()
method
does
not
provide
special
handling
for
offline
storage
or
delivery.
A
beacon
request
is
like
any
other
request
and
may
be
combined
with
[
SERVICE-WORKERS
]
to
provide
offline
functionality
where
necessary.
The
sendBeacon()
method
is
not
intended
to
provide
background
synchronization
or
transfer
capabilities.
The
user
agent
restricts
the
maximum
accepted
payload
size
to
ensure
that
beacon
requests
are
able
to
complete
quickly
and
in
a
timely
manner.
The
sendBeacon()
method
does
not
provide
ability
to
customize
the
request
method,
provide
custom
request
headers,
or
change
other
processing
properties
of
the
request
and
response.
Applications
that
require
non-default
settings
for
such
requests
should
use
the
[
FETCH
]
API
with
keep-alive
flag
set
to
true
.
2.
Conformance
As
well
as
sections
marked
as
non-normative,
all
authoring
guidelines,
diagrams,
examples,
and
notes
in
this
specification
are
non-normative.
Everything
else
in
this
specification
is
normative.
The
key
words
MAY
,
MUST
,
SHOULD
,
and
SHOULD
NOT
in
this
document
are
to
be
interpreted
as
described
in
BCP
14
[
RFC2119
]
[
RFC8174
]
when,
and
only
when,
they
appear
in
all
capitals,
as
shown
here.
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
the
user
agent.
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.)
2.1
Dependencies
DOM
The
following
terms
are
defined
in
the
DOM
specification:
[
DOM
]
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:
The
sendBeacon()
method
transmits
data
provided
by
the
data
parameter
to
the
URL
provided
by
the
url
parameter:
The
user
agent
MUST
initiate
a
fetch
with
keepalive
flag
set,
which
restricts
the
amount
of
data
that
can
be
queued
by
such
requests
to
ensure
that
beacon
requests
are
able
to
complete
quickly
and
in
a
timely
manner.
The
user
agent
MUST
schedule
immediate
transmission
of
all
beacon
requests
when
the
document
visibilityState
transitions
to
hidden
,
and
must
allow
all
such
requests
to
run
to
completion
without
blocking
other
time-critical
and
high-priority
work.
The
user
agent
SHOULD
schedule
transmission
of
provided
data
to
minimize
resource
(CPU
and
network)
contention
with
other
time-critical
and
high
priority
work.
The
user
agent
MAY
delay
transmission
of
provided
data
to
optimize
network
and
energy
efficiency
-
e.g.
deliver
immediately
if
the
network
is
active,
or
wait
until
network
interface
is
active.
However,
the
user
agent
SHOULD
NOT
delay
transmission
indefinitely
and
ensure
that
pending
transmissions
are
periodically
flushed
even
if
there
is
no
other
network
activity.
Note
Beacon
API
does
not
provide
a
response
callback.
The
server
is
encouraged
to
omit
returning
a
response
body
for
such
requests
(e.g.
respond
with
204
No
Content
).
Parameters
url
The
url
parameter
indicates
the
URL
where
the
data
is
to
be
transmitted.
data
The
data
parameter
is
the
BodyInit
data
that
is
to
be
transmitted.
Return
Value
The
sendBeacon()
method
returns
true
if
the
user
agent
is
able
to
successfully
queue
the
data
for
transfer.
Otherwise
it
returns
false.
Note
The
user
agent
imposes
limits
on
the
amount
of
data
that
can
be
sent
via
this
API:
this
helps
ensure
that
such
requests
are
delivered
successfully
and
with
minimal
impact
on
other
user
and
browser
activity.
If
the
amount
of
data
to
be
queued
exceeds
the
user
agent
limit
(as
defined
in
http-network-or-cache-fetch
),
this
method
returns
false
;
a
return
value
of
true
implies
the
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.
3.2
Processing
Model
On
calling
the
sendBeacon()
method
with
url
and
optional
data
,
the
following
steps
must
be
run:
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
"
TypeError
"
exception
and
terminate
these
steps.
Let
headerList
be
an
empty
list.
Let
corsMode
be
"
no-cors
".
If
data
is
not
null
:
Set
transmittedData
and
contentType
to
the
result
of
extracting
data
's
byte
stream
with
the
keepalive
flag
set.
If
the
amount
of
data
that
can
be
queued
to
be
sent
by
keepalive
enabled
requests
is
exceeded
by
the
size
of
transmittedData
(as
defined
in
http-network-or-cache-fetch
),
set
the
return
value
to
false
and
terminate
these
steps.
Note
Requests
initiated
via
the
Beacon
API
automatically
set
the
keepalive
flag,
and
developers
can
similarly
set
the
same
flag
manually
when
using
the
Fetch
API.
All
requests
with
this
flag
set
share
the
same
in-flight
quota
restrictions
that
is
enforced
within
the
Fetch
API.
Fetch
req
,
with
processResponseEndOfBody
set
to
handleBeaconDone
.
4.
Privacy
and
Security
The
sendBeacon()
interface
provides
an
asynchronous
and
non-blocking
mechanism
for
delivery
of
data.
This
API
can
be
used
to:
Report
client-side
events
to
the
server.
The
delivery
is
prioritized
and
scheduled
by
the
user
agent
such
that
it
does
not
block
other
interactive
work
and
makes
efficient
use
of
system
resources.
Report
session
data
when
the
page
transitions
to
background
state
or
is
being
unloaded,
without
blocking
the
user
agent.
Other
use
cases
that
require
delivery
of
small
payloads
and
do
not
expect
a
response
callback.
The
delivered
data
might
contain
potentially
sensitive
information,
for
example,
data
about
a
user's
activity
on
a
web
page,
to
a
server.
While
this
can
have
privacy
implications
for
the
user,
existing
methods,
such
as
scripted
form-submit,
image
beacons,
and
XHR/fetch
requests
provide
similar
capabilities,
but
come
with
various
and
costly
performance
tradeoffs:
the
requests
can
be
aborted
by
the
user
agent
unless
the
developer
blocks
the
user
agent
from
processing
other
events
(e.g.
by
invoking
a
synchronous
request,
or
spinning
in
an
empty
loop),
and
the
user
agent
is
unable
to
prioritize
and
coalesce
such
requests
to
optimize
use
of
system
resources.
A
request
initiated
by
sendBeacon()
is
subject
to
following
properties:
If
the
request
does
not
contain
a
payload,
or
the
request
Content-Type
is
a
CORS-safelisted
request-header
,
then
the
request
mode
is
no-cors
—similar
to
an
image
beacon
or
form-post
respectively.
As
such,
from
the
security
perspective,
the
Beacon
API
is
subject
to
same
security
policies
as
the
current
methods
in
use
by
developers.
Similarly,
from
the
privacy
perspective,
the
resulting
requests
are
initiated
immediately
when
the
API
is
called,
or
upon
a
page
visibility
change,
which
restricts
the
exposed
information
(e.g.
user's
IP
address)
to
existing
lifecycle
events
accessible
to
the
developers.
However,
user
agents
might
consider
alternative
methods
to
surface
such
requests
to
provide
transparency
to
users.
Compared
to
the
alternatives,
the
sendBeacon()
API
does
apply
two
restrictions:
there
is
no
callback
method,
and
the
payload
size
can
be
restricted
by
the
user
agent.
Otherwise,
the
sendBeacon()
API
is
not
subject
to
any
additional
restrictions.
The
user
agent
ought
not
skip
or
throttle
processing
of
sendBeacon()
calls,
as
they
can
contain
critical
application
state,
events,
and
analytics
data.
Similarly,
the
user
agent
ought
not
disable
sendBeacon()
when
in
"private
browsing"
or
equivalent
mode,
both
to
avoid
breaking
the
application
and
to
avoid
leaking
that
the
user
is
in
such
mode.
A.
Acknowledgments
Thanks
to
Alois
Reitbauer,
Arvind
Jain,
Anne
van
Kesteren,
Boris
Zbarsky,
Chase
Douglas,
Daniel
Austin,
Jatinder
Mann,
James
Simonsen,
Jason
Weber,
Jonas
Sicking,
Nick
Doty,
Philippe
Le
Hegaret,
Todd
Reifsteck,
Tony
Gentilcore,
William
Chan,
and
Yoav
Weiss
for
their
contributions
to
this
work.