Unofficial
Draft
20
December
2022
Copyright
©
2022
2023
the
document
editors/authors.
Text
is
available
under
the
Creative
Commons
Attribution
4.0
International
Public
License
;
additional
terms
may
apply.
This
specification
defines
an
API
allowing
web
pages
and
that
allows
installed
web
applications
to
set
a
badge
on
the
document,
or
an
application-wide
application
badge,
which
is
usually
shown
in
an
operating-system-specific
place
associated
with
alongside
the
application
(such
as
application's
icon
on
the
shelf
or
device's
home
screen),
for
the
purpose
of
notifying
the
user
when
the
state
of
the
page
screen
or
application
has
changed
(e.g.,
when
new
messages
have
arrived),
without
showing
a
more
heavyweight
notification.
dock.
This document is a draft of a potential specification. It has no official standing of any kind and does not represent the support or consensus of any standards organization.
This
is
an
early
draft
of
the
Badging
API
spec.
a
work
in
progress.
This section is non-normative.
async function updateMailBadge() { // Check if the API is supported. if (!navigator.setAppBadge) return;
const unreadCount = await getUnreadMailCount();
:
Showing
ready
status
for
this
document
{
(playerTurnId === localPlayerId)
navigator.setClientBadge();
navigator.clearClientBadge();
// Try to set the app badge.
try {
await navigator.setAppBadge(unreadCount);
} catch (e) {
// The badge is not supported, or the user has prevented the app // from setting a badge.
}
}
A
separate
set
of
methods
set
the
badge
on
the
installed
web
application
,
if
any,
whose
navigation
scope
this
document
is
within.
The
badge
might
show
up
on
the
application's
icon
in
the
operating
system
shelf.
These
examples
work
the
same
as
above,
except
that
the
badge
has
global
scope
(if
system.
If
multiple
documents
API
calls
within
the
same
application
set
or
clear
a
badge,
the
most
recent
one
takes
effect),
effect,
and
can
may
continue
being
seen
even
after
the
last
document
closes.
an
application
is
closed.
async function showPlayerTurn(playerTurnId) {
if (playerTurnId === localPlayerId)
await navigator.setAppBadge();
else
await navigator.clearAppBadge();
}
On
some
operating
systems
setting
a
badge
can
require
permission
from
the
user.
In
this
case,
a
developer
need
to
query
the
"
notifications
"
permissions
status
before
setting
a
badge.
If
the
permission
is
not
granted,
the
developer
will
need
to
prompt
for
permission
via
the
Notification
.
requestPermission
()
.
async function checkPermission() {
permission = await navigator.permissions.query({
name: "notifications",
});
const button = document.getElementById("permission-button"); if (permission.state === "prompt") { // Prompt the user to grant permission.
button.hidden = false;
button.addEventListener("click", async () => {
await Notification.requestPermission();
checkPermission();
}, { once: true });
return;
}
button.hidden = true;
}
A
badge
may
be
is
intended
as
a
mechanism
for
installed
web
applications
to
notify
the
user
that
there
is
some
new
activity
that
might
require
their
attention,
or
as
a
way
of
indicating
a
small
amount
of
information,
such
as
an
unread
count.
A
badge
can
have
one
of
the
following
values:
values
:
0
.
Each
document
and
each
An
installed
web
application
is
has
an
associated
with
a
badge
value,
,
which
is
initialized
to
nothing
"nothing"
.
The
user
agent
MAY
reset
(re)
set
an
application's
badge
to
nothing
"nothing"
at
its
discretion
(for
example,
when
the
following
system
is
restarted).
If
a
badge
is
nothing
,
it
is
said
to
be
"
cleared
".
Otherwise,
it
is
said
to
be
"
set
".
conventions).
When
a
document's
the
application's
badge
is
set
,
if
the
document's
browsing
context
is
a
top-level
browsing
context
,
,
the
user
agent
or
operating
system
SHOULD
display
the
document's
application's
badge
value
alongside
the
other
identifying
information
for
that
document
primary
iconic
representation
of
the
application
in
the
user's
operating
system
(for
example,
as
a
small
overlay
on
top
of
the
document's
application's
icon
or
near
its
title).
Note
The
user
agent
is
not
expected
to
display
a
badge
associated
with
a
document
that
is
not
on
the
home
screen
on
a
top-level
browsing
context
,
although
it
is
allowed
to.
device).
A
user
agent
does
not
need
MAY
require
express
permission
from
the
user
to
store
set
the
badge
for
badge.
When
a
non-top-level
browsing
context
if
user
agent
requires
such
permission
,
it
does
not
intend
SHOULD
tie
the
permission
grant
to
display
it.
the
"
notifications
"
permission.
When
the
application's
badge
is
set
to
"flag"
,
the
user
agent
or
operating
system
SHOULD
display
the
application's
an
indicator
with
a
non-specific
symbol
(for
example,
a
colored
circle).
When
a
badge
alongside
any
symbolic
representations
of
the
application
in
's
value
is
set
to
"nothing"
,
the
user's
user
agent
or
operating
system
(for
example,
as
a
small
overlay
on
top
of
SHOULD
clear
the
application's
icon).
badge
by
no
longer
displaying
it.
If
When
the
badge
is
set
to
special
value
flag
a
number
,
the
user
agent
or
operating
system:
When
To
set
the
application
badge
of
platform
object
context
to
an
optional
setAppBadge
unsigned
long
long
()
method
is
called
with
argument
contents
:
value:
Window
object,
then:
Document
DOMException
InvalidStateError
.
NotSupportedError
SecurityError
"
setAppBadge
granted
Document
NotAllowedError
undefined
.
The API is write-only by design. There is no way for a site to read back the value of a badge that was previously set, to ensure that the application badge cannot be used as a storage or fingerprinting mechanism.
The user agent or operating system MAY clear a badge at its discretion, and to follow any system conventions (for example, when the system is reset).
For
installed
apps,
showing
badges
makes
sense,
because
of
the
song-and-dance
the
users
have
Raised
by
@grorg
on
webkit-dev
:
I'd also like to
go throughsee some specification text describing how the browser should ignore multiple set/clear operations executed in rapid succession (e.g. toinstallcreate aweb apps. However, I wonder if we need to gateblinking badge) - maybe theAPI usinglimit is one badge operation per minute or something?
We
should
address
this;
it
might
be
a
permission
recommendation
rather
than
a
requirement,
since
it
relates
to
mitigate
tabs
unnecessarily
drawing
the
user's
attention?
UI
of
the
user
agent.
I'd
like
to
see
some
sort
of
"eventual
consistency"
guarantee
which
says
that
the
final
value
you
write
to
the
badge
will
eventually
be
the
one
displayed
to
the
user.
This
could
potentially
prevents
a
situation
where
you
set
"3"
then
10
seconds
later
set
"12",
and
due
to
rate
limiting,
the
"12"
never
gets
set,
so
the
user
just
sees
"3"
forever.
Instead,
the
rule
should
be
handled
at
"If
the
UI
layer...
just
putting
this
here
for
discussion.
hasn't
been
updated
in
>
N
seconds,
update
it
to
the
new
value.
Otherwise,
set
a
timer
to
update
the
UI
to
the
new
value
in
N
-
(however
long
it
has
been
since
the
last
update)
seconds."
This section is non-normative.
If the browser is in the control of presenting the badge, it should be possible to define some accessibility guidelines.
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
NOT
,
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.
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: