Register for this year’s #ChromeDevSummit happening on Nov. 11-12 in San Francisco to learn about the latest features and tools coming to the Web. Request an invite on the Chrome Dev Summit 2019 website

Badging for App Icons

We’re currently working on this API as part of the new
capabilities project, and starting
in Chrome 73 it is available as an origin trial.
This post will be updated as the Badging API evolves.Last Updated: August 21st, 2019

What is the Badging API?

Example of Twitter with 8 notifications and another app showing a flag
type badge.

The Badging API is a new web platform API that allows installed web apps to
set an application-wide badge, shown in an operating-system-specific place
associated with the application (such as the shelf or home screen).

Badging makes it easy to subtly notify the user that there is some new
activity that might require their attention, or it can be used to indicate a
small amount of information, such as an unread count.

Badges tend to be more user-friendly than notifications, and can be updated
with a much higher frequency, since they don’t interrupt the user. And,
because they don’t interrupt the user, there’s no special permission needed
to use them.

See it in action

When prompted, click Install to install the app , or use the Chrome
menu to install it, then open it as an installed PWA. Note, it must be
running as an installed PWA (in your task bar or dock).

Click the Set or Clear button to set or clear the badge from the app
icon. You can also provide a number for the Badge value.

Note: While the Badging API in Chrome requires an installed app
with an icon that actually can be badged, we advise against
making calls to the Badging API dependent on the install state.
The Badging API can apply to anywhere a browser might want to show a badge,
so developers shouldn’t make any assumptions about in what situations
the browser will make badges work. Just call the API when it exists.
If it works, it works. If not, it simply doesn’t.

How to use the Badging API

Starting in Chrome 73, the Badging API is available as an origin trial
for Windows (7+) and macOS.
Origin trials allow you to try out new features and give
feedback on usability, practicality, and effectiveness to us, and the web
standards community. For more information, see the
Origin Trials Guide for Web Developers.

Support for badging across platforms

The Badging API is supported (in an origin trial) on Windows and macOS.
Android is not supported because it requires you to show a notification,
though this may change in the future.
Chrome OS support is pending implementation of badging on the platform.

Register for the origin trial

Add the token to your pages, there are two ways to provide this token on
any pages in your origin:

Add an origin-trial<meta> tag to the head of any page. For example,
this may look something like:
<meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">

If you can configure your server, you can also provide the token on pages
using an Origin-Trial HTTP header. The resulting response header should
look something like: Origin-Trial: TOKEN_GOES_HERE

Alternatives to the origin trial

If you want to experiment with the Badging API locally, without an origin trial,
enable the #enable-experimental-web-platform-features flag in chrome://flags.

Using the Badging API during the origin trial

Dogfood: During the origin trial, the API will be available via
window.ExperimentalBadge. The below code is based on the current design,
and will change before it lands in the browser as a standardized API.

ExperimentalBadge.set() and ExperimentalBadge.clear() can be called from
a foreground page, or potentially in the future, a service worker. In either
case, it affects the whole app, not just the current page.

In some cases, the OS may not allow the exact representation of the badge,
in this case, the browser will attempt to provide the best representation for
that device. For example, while the Badging API isn’t supported on Android,
Android only ever shows a dot instead of a numeric value.

Note: Don’t assume anything about how the user agent wants to display the badge.
We expect some user agents will take a number like "4000" and rewrite it as "99+".
If you saturate it yourself (for example to "99") then the "+" won’t appear.
No matter the actual number, just set Badge.set(unreadCount)
and let the user agent deal with displaying it accordingly.

Feedback

We need your help to ensure that the Badging API works in a way that meets your
needs and that we’re not missing any key scenarios.

We need your help! - Will the current design
(allowing either an integer or a flag value) meet your needs?
If it won’t, please file an issue in the
WICG/badging repo
and provide as much detail as you can. In addition,
there are a number of
open questions that are still being discussed, and we’d be interested to
hear your feedback.