Adding Notification Badges to Progressive Web Apps

Last Updated - Sat Jan 09 2021

We have all seen those numbers displayed to the top right of icons on our phones. They tell us how many unread messages, waiting updates and more things that need out attention.

They create a monetary sense of urgency to open the app and see what is waiting.

Of course that sense remains until we grow fatigued due to weak payoffs. Many have grown a blindness to these enticing visual hooks.

As a developer the good news is we can now manage native badges in progressive web applications.

You will learn how the web badging API works and how to add it to your PWAs. You will see how to pair badging with background APIs to keep your badges current.

I hope to share how to use badges responsibly so your user's do not ignore your badges.

Badges on task bar, start menu and homescreen icons are one way to visually convey the user's state.

You can use badging inside your application too. After covering the native API I will show how to use badges within your application.

This should serve as a reference for your to add badging to your PWAs. They engage the user from the OS and within your application. You will learn how to use the native badging API to update in the background and strategies to keep your in app badges up to date.

What is an App Icon Badge

Icon badges are circles or ovals containing a number displayed in one corner of the app icon. They may also be a simple dot.

Icons are rendered in a contrasting color from the icon. On iOS the badges are a bright red background with white text. Android uses a similar metaphor. Windows uses a black background with white text.

The purpose of an app badge is to convey to the user glanceable way to see how many items need their attention. A common use case is to display how many unread email messages may be waiting.

The badge is a power of the homescreen, start menu or task bar icon to draw the consumer into opening the application. The more they open your app the more likely they are to become a loyal customer.

Don't limit the use of badges to the operating system icon. The visual metaphor can add power to your application once it is opened. I will cover some of these cases later in the article.

App Badges Use Cases

I mentioned displaying an unread e-mail count as a use case earlier. Similarly you could display unread messages, phone calls, voice mails, etc. These are all communication related.

Messages
Task State
Action Required

But what about displaying items that require attention. For example maybe the user needs to check-in within a period of time.

Maybe the user started a long running task in the cloud and you need to convey the current state, running, finished, error, etc.

For this site I am using this feature to let readers know a new article, video or resource has been published. I am working on a new PWA right now that will use it to prompt the user to check-in each day. We also want to notify the user of unread messages and general communication.

Other apps I have developed can notify employees to new orders to process, shipping states, or work items completed.

The Badging API

The API is simple. Two functions, setAppBadge and clearAppBadge. These methods are part of the navigator object.

You can access these functions from both the UI and service worker.

Both methods are asynchronous, like all modern browser APIs. That means they return a Promise. You can use classic promise syntax, which I tend to prefer, or the async await pattern.

Feature Detection

Before engaging with modern APIs you should always do feature detection before engaging the functions.

if( "setAppBadge" in navigator &amp;amp;&amp;amp; "clearAppBadge" in navigator){

	//use the native badge API

}

As I write this, Edge, Chrome and Samsung Internet support the API. Safari and FireFox do not. So don't let your site throw an exception because the user agent does not support modern APIs.

The functions are also not available if the site has not been added to the user's homescreen.

Setting the Badge

The setAppBadge method has a single, optional value. It is a number, or can be empty. If a number is passed the browser can display this number or a simple dot. If no value is passed only the dot will be displayed.

navigator.setAppBadge(badgeCount).catch((error) =&amp;gt; {

  //Do something with the error.

});

You cannot remove a badge by calling the setAppBadge function. This method causes a badge to be displayed, it does not clear or remove the badge.

I said you will see either a number or a dot. There is not guarantee how your badge will be displayed it is up to the user agent to decide. You will at least get the small dot badge to indicate something needs attention.

Clearing the Badge

To clear an existing badge you need to call the clearAppBadge function. It receives no values or parameters.

navigator.clearAppBadge().catch((error) =&amp;gt; {

  // Do something with the error.

});

Calling this function removes any displayed badge.

How the User Agent (Browser) Displays the Badge

On the desktop, Edge and Chrome will display the number supplied in the setAppBadge function call. This is not required. The user agent can display the badge however it likes.

Chrome on Android, for now, displays a simple dot, not the numeric value.

For now, the badging API is only available in Edge, Chrome and Samsung Internet. These browsers represent the majority of the world's browser usage.

Unfortunately this is an API Apple has not integrated to Safari. This leaves iPhone and Safari desktop users out of the enhanced experience for now.

Using the API

The badging API is simple, a couple of functions. So there are responsibilities that fall on you to manage.

You also need to realize the operating system badge will only work if the user has installed or added the PWA to the homescreen. This makes sense because the badge needs an icon to display. If the PWA has not been installed there is no icon to orbit.

Adding badging to your application requires careful planning and coding. You need to consider the visual queue is tied to the individual user, not a global state.

To handle this you should add APIs to manage the user's state. You should also perform periodic updates. These updates can be driven by a background sync cadence or live application updates.

Using API with Periodic Background Sync

The native badging API is great. But without a way to update the user's application state while they are away it does not provide much value.

Pairing the badging with the Periodic Background Sync (PBS), you can silently update the badge state in regular intervals.

Because badge updates are passive no user permission is required. The API provides no way for a site to do anything beyond setting a number or display badge state

Because the badge API needs the PWA to be installed, you have access to the periodic background sync API.

Beyond being installed the PWA will also need to have a minimal site engagement score. The score ranges from 0 to 100. 100 equates to frequent usage and 0 means none. As I understand the current state you need a score higher than 0. I think if someone installs the site then your engagement score is above 0.

Of course this does not guarantee the user will continue to use the app. If the engagement score decays to 0 then PBS will stop triggering until the score raises.

This makes sense. If the user is not engaging with the app, don't waste resources.

This will be a quick intro to the periodic background sync API. Please read my more comprehensive article to learn how to use it.

//example of setting up the PBS

The gist of the PBS is to define a tag and an update frequency. The API will trigger an event using a cadence matching the tag's frequency.

When the PBS event triggers you should have a handler. The handler should match the tag to a handler function. For example you can define a method called badgeState to execute an update routine for your application's badge.

//example of handling the PBS event

I will cover an example of the update routine later. Next let's see how to pair the badge API with the native Push API.