What is the Badging API?
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.
Suggested use cases for the badging API
Examples of sites that may use this API include:
- Chat, email and social apps, to signal that new messages have arrived, or show the number of unread items
- Productivity apps, to signal that a long-running background task (such as rendering an image or video) has completed.
- Games, to signal that a player action is required (e.g., in Chess, when it is the player's turn).
|1. Create explainer||Complete|
|2. Create initial draft of specification||Complete|
|3. Gather feedback & iterate on design||In progress|
|4. Origin trial||In progress|
|5. Launch||Not started|
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
- Request a token for your origin.
- Add the token to your pages, there are two ways to provide this token on
any pages in your origin:
- Add an
<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
Origin-TrialHTTP header. The resulting response header should look something like:
- Add an
Using the badging API during the origin trial
To use the badging API, your web app needs to meet Chrome’s installability criteria, and a user must add it to their home screen.
ExperimentalBadge interface is a member object on
window. It contains
set([number]): Sets the app's badge. If a value is provided, set the badge to the provided value otherwise, display a plain white dot (or other flag as appropriate to the platform).
clear(): Removes app's badge.
// In a web page const unreadCount = 24; window.ExperimentalBadge.set(unreadCount);
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.
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’re also interested to hear how you plan to use the Badging API:
- Have an idea for a use case or an idea where you'd use it?
- Do you plan to use this?
- Like it, and want to show your support?
Share your thoughts on the Badging API WICG Discourse discussion.
- Public explainer
- Tracking bug
- ChromeStatus.com entry
- Request an origin trial token
- How to use an origin trial token
- Blink Component: