Implementing Badge Notifications for Uno Platform WebAssembly

Web Uno Platform WinUI

2 years ago

Badge notifications provide the user a way to quickly see a numeric notification directly on the application icon either on the mobile app home screen or on the taskbar. Previously, this feature was available only on iOS and macOS targets of Uno Platform. Android does not have a standardized approach to show badge notifications on app icons yet, and there was no such web API available either. This has however changed when W3C published first draft of web Badging API. In this article I will share how I implemented the BadgeUpdateManager API in Uno Platform WebAssembly using this new API.

Badging API in action

Badging API in action

Web Badging API

The web Badging API provides a very simple set of methods to set and clear the badge:

There is also a similar set of methods setClientBadge and clearClientBadge – these are very similar, but can only be used when the app is running (whereas setAppBadge and clearAppBadge can also be utilized from service worker). It is also important to note, that the badge is only set when the app is running as PWA on the device – it will not be applied when the app is just running as a tab within the context of a browser (at least currently).

Badge notifications in UWP

To support badge notifications in Uno Platform, we need to map this functionality on the UWP API. At the core is the BadgeUpdateManager class, which first provides us with a XML template which we can modify and then create a BadgeNotification. After that, we can use BadgeUpdater.Update to send the notification.

So it's time to implement this!

BadgeNotification

Let's start with the BadgeNotification class. This one is fairly easy, as it is just a container for the customized XML template of the notification.

I am skipping here over a "small detail" which is the XmlDocument implementation. UWP uses a custom set of XML classes here, which closely mimic the built in .NET System.Xml namespace classes. Implementing these was a necessary prerequisite and I did that in another PR, which you can find here, in case you are interested.

BadgeUpdateManager

Next up, BadgeUpdateManager. For our purposes we need just two methods:

CreateBadgeUpdaterForApplication just creates a new instance of BadgeUpdater which we will look into next. GetTemplateContent should return the XmlDocument template that the developer then modifies to set the badge value. Interestingly, even though UWP supports two different badge template types, both actually return the exact same XML, so that's also reflected in our code.

BadgeUpdater

Here comes the most interesting part of our implementation: BadgeUpdater this is the class that is actually responsible for applying the badge on the app icon. Uno Platform has many platform targets, so usually implementations of various UWP/WinUI APIs have some shared logic which leads to a platform specific handling in the end. Let's focus on the shared part first:

The constructor just performs a platform-specific initialization (if there is need for one). In the Update method, we essentially "unpack" the interesting part of the badge notification's XML (we are only interested in the value attribute's value). When we have it, we send it to the partial method called SetBadge, which is platform specific and will handle the rest. Finally, the Clear method just calls SetBadge again, just with a null argument. So how does the WebAssembly platform-specific code look? Let's see!

As the Web Badging API can only handle numeric badges, we parse the string to an int, and if successful, we invoke a TypeScript function, which is conveniently exposed on a class with the same name and namespace. For clearing the badge, we have another function with the same name.

TypeScript implementation

So the final piece of our puzzle is the TypeScript counterpart of the BadgeUpdater.

As we did most of the heavy lifting in the managed code, we essentially just forward our "request" to the Web Badging API here. Note I needed to declare the methods in the Navigator interface, as the type definitions were not yet available in the TypeScript version Uno Platform is currently using (mostly because the Web Badging API is still a draft). In addition, I needed to omit the fact that the Web Badging API is using Promises. Unfortunately UWP/WinUI does not offer awaitable version of the BadgeUpdater methods, so we need to assume the user will not call these in quick succession and that the previous request will predictably be resolved before the next one.

Summary

And that's it folks! In not-so-many lines of code it was possible to bring the UWP/WinUI API to Uno Platform WebAssembly, so now you can just write your Windowsy code and it will then light up and work without any changes on the web as well. If you want to review the whole PR, you can check it here. To make it even more interesting, it also contains the Tizen platform implementation. Feel free to try this API out in your apps too and let me know what you think!