Implementing the App Badging API in Android TWAs

For communications software, project management tools, and transactional platforms, keeping users informed of unread events is a core product requirement. On mobile platforms, this is traditionally achieved using native notification badges on the app icon. By leveraging the Web App Badging API, Progressive Web Apps (PWAs) running inside an Android Trusted Web Activity (TWA) can native-style badge counts directly from JavaScript.

How the App Badging API Operates inside a TWA

The App Badging API consists of two primary JavaScript methods exposed on the global navigator object: setAppBadge and clearAppBadge. These methods allow web developers to pass an integer value to the operating system, which is then rendered on the application icon on the user's home screen or app drawer.

When your web app runs inside a TWA, the underlying browser engine (typically Google Chrome on Android) intercepts these JavaScript API calls. The browser engine processes the request and communicates directly with the Android ShortcutManager or the system launcher's badging APIs. This translation layer ensures that your standard web code seamlessly updates the native Android launcher icon without requiring custom Java or Kotlin classes inside your wrapper.

Implementing the JavaScript API in Your PWA

Before executing badging calls, your code should verify feature support. Different browsers and operating systems handle badging differently, so fallback patterns are essential. The following steps outline how to implement badging directly inside your frontend application code.

Checking for Feature Support

To prevent runtime errors, wrap your badging logic in a feature detection block. This is particularly important for supporting legacy devices or alternative web runtimes that do not support the API.

if ('setAppBadge' in navigator) { console.log('App Badging API is supported'); }

Setting the Badge Count

To display a specific number on your launcher icon, call the setAppBadge method and pass an integer. Google Play and Android launcher environments generally display numeric badges up to a certain threshold, after which they may truncate or display a simple dot indicator depending on launcher settings.

function updateUnreadCount(count) { if ('setAppBadge' in navigator) { navigator.setAppBadge(count).catch((error) => { console.error('Error setting badge:', error); }); } }

Clearing the Badge

When the user reads the notifications or clears their inbox, you must explicitly clear the badge. You can achieve this by passing zero to the setAppBadge method, or by calling the clearAppBadge method directly.

function clearUnreadCount() { if ('clearAppBadge' in navigator) { navigator.clearAppBadge().catch((error) => { console.error('Error clearing badge:', error); }); } }

Updating Badges from a Web Push Event

In many production scenarios, you will want to update the app badge when the application is closed. To do this, you must interact with the App Badging API from within your Service Worker file. When your service worker intercepts a push notification event, you can run badging logic in the background.

Inside your service worker file, the API is exposed on the self.navigator interface. Here is how you can handle this during a push notification event:

self.addEventListener('push', (event) => { const data = event.data ? event.data.json() : {}; const unreadCount = data.unreadCount || 1; const badgePromise = self.navigator.setAppBadge(unreadCount); event.waitUntil(Promise.all([ badgePromise, self.registration.showNotification('New Message', { body: data.message }) ])); });

Using event.waitUntil ensures that the operating system keeps the service worker thread active long enough to complete both the badge update and the notification presentation.

Android Launcher Compatibility and Limitations

While the App Badging API is standardized, the visual execution on Android depends entirely on the device's system launcher. Android OEMs (Original Equipment Manufacturers) like Samsung, Xiaomi, OnePlus, and Google implement varying rules for icon badges. The table below displays how common Android launchers render badges received from a TWA.

It is important to communicate to users that the appearance of a badge (whether it is an exact number or a simple coloured dot) is governed by their Android system settings and launcher choice. Developers cannot force a numeric badge if the user's launcher settings are configured to only display dots.

Troubleshooting Common Badging Issues in TWAs

If your TWA is running but your application icon fails to show a badge, verify the following elements of your setup:

First, check notification permissions. Under recent Android versions, notification permissions are highly guarded. If the user has completely blocked notifications for your app, Chrome may limit or entirely disable the background service worker's ability to call setAppBadge. Ensure you prompt users to allow notifications gracefully within your application interface.

Second, confirm browser compatibility. A TWA relies on Chrome Custom Tabs. If Chrome is disabled, or if the default system browser has been swapped to an alternative that does not fully support the App Badging spec, the API calls will silently fail. Ensure your application handles promise rejections gracefully so that background processes are not disrupted.

Third, verify the manifest file configuration. Your Web App Manifest must be correctly declared and linked. The package name of your TWA must be linked properly via Digital Asset Links to your domain. If the operating system cannot guarantee that the running TWA corresponds to the web domain calling setAppBadge, it will deny permission to modify the launcher icon to prevent spoofing attacks.