The App Badging API allows installed web apps to set an application-wide badge on the app icon.

Pete LePage

What is the App Badging API?

The App 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 activitythat might require their attention, or to indicate a small amount ofinformation, such as an unread count.

Badges tend to be more user-friendly than notifications, and can be updatedwith 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 apps that might use this API include:

• Chat, email, and social apps, to signal that new messages have arrived, or toshow the number of unread items.
• Productivity apps, to signal that a long-running background task (such asrendering an image or video) has completed.
• Games, to signal that a player action is required (e.g., in Chess, when itis the player's turn).

Support

The App Badging API works on Windows, and macOS, in Chrome 81 and Edge 81 or later.Support for ChromeOS is in development and will be available in a futurerelease. On Android, the Badging API is not supported. Instead,Android automatically shows a badge on app icon for the installed web appwhen there is an unread notification, just as for Android apps.

Try it

1. Open theApp Badging API demo.
2. When prompted, clickInstall to install the app, or use the Chromemenu 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 theSet orClear button to set or clear the badge from the appicon. You can also provide a number for theBadge value.

How to use the App Badging API

To use the App Badging API, your web app needs to meetChrome's installability criteria,and users must add it to their home screens.

The Badge API consists of two methods onnavigator:

• setAppBadge(number): Sets the app's badge. If a value is provided, set thebadge to the provided value otherwise, display a plain white dot (or otherflag as appropriate to the platform). Settingnumber to0 is the same ascallingclearAppBadge().
• clearAppBadge(): Removes the app's badge.

Both return empty promises you can use for error handling.

The badge can either be set from the current page, or from the registeredservice worker. To set or clear the badge (in either the foreground page orthe service worker), call:

// Set the badgeconstunreadCount=24;navigator.setAppBadge(unreadCount).catch((error)=>{//Do something with the error.});// Clear the badgenavigator.clearAppBadge().catch((error)=>{// Do something with the error.});

In some cases, the operating system may not allow the exact representation of the badge.In such cases, the browser will attempt to provide the best representation forthat device. For example, because the Badging API isn't supported on Android,Android only ever shows a dot instead of a numeric value.

Don't assume anything about how the user agent displays the badge.Some user agents may take a number like "4000" and rewrite it as"99+". If you saturate the badge yourself (for example by setting it to "99")then the "+" won't appear. No matter the actual number, just callsetAppBadge(unreadCount) and let the user agent deal withdisplaying it accordingly.

While the App Badging APIin Chrome requires an installed app, you shouldn'tmake calls to the Badging API dependent on the install state. Just call theAPI when it exists, as other browsers may show the badge in other places.If it works, it works. If not, it simply doesn't.

Setting and clearing the badge in the background from a service worker

You can also set the app badge in the background using the service worker. Do this eitherthrough periodic background sync, the Push API, or a combination of both.

Periodic background sync

Periodic background sync allows a service workerto periodically poll the server, which could be used to get an updated status,and callnavigator.setAppBadge().

However, the frequency at which the sync is called isn't perfectly reliable,and is called the at discretion of the browser.

Web Push API

ThePush API allows servers to send messages to service workers,which can run JavaScript code even when no foreground page is running. Thus,a server push could update the badge by callingnavigator.setAppBadge().

However, most browsers, Chrome included, require a notification to bedisplayed whenever a push message is received. This is fine for some usecases (for example showing a notification when updatingthe badge) but makes it impossible to subtly update the badge withoutdisplaying a notification.

In addition, users must grant your site notification permission in order toreceive push messages.

A combination of both

While not perfect, using Push API and periodic background sync togetherprovides a good solution. High priority information is delivered via the PushAPI, showing a notification and updating the badge. And lower priorityinformation is delivered by updating the badge, either when the page is open,or via periodic background sync.

Feedback

The Chrome team wants to hear about your experiences with the App Badging API.

Tell us about the API design

Is there something in the API that doesn't work as you expected? Or arethere missing methods or properties that you need to implement your idea?Do you have a question or comment on the security model?

• File a spec issue on theBadging API GitHub repo, or add yourthoughts to an existing issue.

Report a problem with the implementation

Did you find a bug with Chrome's implementation? Or is the implementationdifferent from the spec?

• File a bug athttps://new.crbug.com. Be sure to include as much detail asyou can, simple instructions for reproducing, and setComponents toUI>Browser>WebAppInstalls.Glitch works great forsharing quick and easy reproductions.

Show support for the API

Planning to use the App Badging API on your site? Your public support helps theChrome team to prioritize features, and shows other browser vendors how criticalit is to support them.

• Send a tweet to@ChromiumDev using the hashtag#BadgingAPIand let us know where and how you're using it.

Helpful links

• Public explainer
• Spec draft
• Badging API Demo |Badging API Demo source
• Tracking bug
• ChromeStatus.com entry
• Blink Component:UI>Browser>WebAppInstalls

Herophoto byPrateek Katyal onUnsplash