What is the Badging API? #

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

The Badging API 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 new activity that might require their attention, or 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, they don’t need the user’s permission.

Possible use cases #

Examples of sites that may use this API include:

• Chat, email, and social apps, to signal that new messages have arrived, or to 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).

Current status #

StepStatus1. Create explainerComplete2. Create initial draft of specificationComplete3. Gather feedback & iterate on designComplete4. Origin trialChrome 79-80 In progress5. LaunchChrome 81

Try it #

1. Using Chrome 81 or later on Windows or Mac (or Chrome 79 or 80, if you’re still participating in the origin trial), open the Badging API demo.
2. When prompted, click Install to install the app, or use the Chrome menu to install it.
3. Open it as an installed PWA. Note, it must be running as an installed PWA (in your task bar or dock).
4. 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.

How to use the Badging API #

The Badging API works on Windows, and macOS. Support for Chrome OS is in development and will be available in a future release of Chrome. On Android, the Badging API is not supported. Instead, Android automatically shows a badge on a web app when there is an unread notification, just as for native apps.

Register for the origin trial #

The origin trial is supported in both Chrome 79 and Chrome 80 and runs through September 2020.

Origin trials allow you to try new features and give feedback on their usability, practicality, and effectiveness to the web standards community. For more information, see the Origin Trials Guide for Web Developers. To sign up for this or another origin trial, visit the registration page.

1. Request a token for your origin.
2. Add the token to your pages. There are two ways to do that:

• Add an origin-trial <meta> tag to the head of each 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 add the token using an Origin-TrialHTTP header. The resulting response header should look something like:
• Origin-Trial: TOKEN_GOES_HERE

#mobileapp