Proposal: Converged and improved badge APIs

[SetTrend]

Summary

Status

Customer / job-to-be-done: App developers need to keep their users informed about number of new items/etc via badges on the taskbar regardless of whether their app is currently open Problem: Win32 apps have a different API for using badges on taskbar, with completely different functionality than UWP apps. Win32 apps can't simply set a number (they have to use custom icons), and UWP apps can only use preset badge/number options (they can't use custom icons). How does our solution make things easier? All types of apps will benefit from a single, easy-to-use badge API, that supports straightforward numbers and common symbols in addition to custom icons.

❌ Problem validation ❌ Docs ❌ Dev spec ❌ Solution validation ❌ Implementation ❌ Samples

Target customer

Packaging	App types
✅ Packaged apps ✅ Unpackaged apps	✅ WPF ✅ Win32 (C++) ✅ WinForms ✅ Console ✅ UWP ⚠ Cross-plat (Electron, MAUI, React Native, etc) ⚠ PowerShell

While this work should be consumable by cross-platform platforms to improve experiences there, we should have a separate feature specifically for ensuring badges are built in "natively" and developers don't have to do additional custom work to access the Windows native layer.

Customer's job-to-be-done

Developer needs to keep their users informed via badges regardless of whether their app is currently open. They may need advanced functionality like custom icons, or might just need simple functionality like setting a number.

Problems that exist today

Problem	Validated?
TODO: Fill this out	❌ TODO

Summary

Converge badge APIs across Win32 and UWP, and also provide objects for the APIs rather than XML (bring in the Toolkit helpers into Reunion itself).

public class BadgeUpdater
{
  public void Update(byte newValue) {...}
  public void Update(BadgeGlyph newValue) {...}

  //...

  public enum BadgeGlyph
  {
    None,
    Activity,
    Alarm,
    //...
  }

  //...
}

Rationale

Manipulating XML text doesn't seem either compile-time safe nor adequate when programming in a programming language.

XML isn't a programming language, it's a serialization medium, like YAML, JSON or plain text.

Editing plain text in terms of XML doesn't provide compile-time safety nor does it support IntelliSense.

Hence, for API purity I suggest do add these two type-safe overloads to the API, basically implementing the two functions documented in the documentation.

Additional ask for this here: microsoft/microsoft-ui-xaml#1919

[michael-hawker]

🦙 FYI @andrewleader does this fall into your purview as well? Thoughts?

[soumyamahunt]

Personally, I would like the tile and taskbar badges to be separated APIs. This will help multi-instance or multi-window UWP apps to set/update badges on each instance or window. Right now only the primary instance or window in taskbar shows badges which isn't that user friendly.

[andrewleader]

@soumyamahunt do your apps have windows that don't appear "glommed" (grouped) together on Taskbar? Most apps always appear glommed together and thus there's only one badge and no point for badges per window...

I'm trying to find out if you're wanting separate badges even when the windows are glommed (like when you hover over and the window previews appear, each one of those has individual separate badges?) or if your app simply avoids glomming the windows and appears as separate instances on taskbar. Any more context/details behind your scenario would be super helpful!

[soumyamahunt]

@soumyamahunt do your apps have windows that don't appear "glommed" (grouped) together on Taskbar? Most apps always appear glommed together and thus there's only one badge and no point for badges per window...

The way I think about badges is that it prompts user to do some tasks by opening a specific window/instance of app. Even if app's windows are grouped together if there is only one badge displayed on the left most window, then we are passing the burden to user to find out in which window/instance of the app demands their attention which isn't that convenient to user.

I'm trying to find out if you're wanting separate badges even when the windows are glommed (like when you hover over and the window previews appear, each one of those has individual separate badges?) or if your app simply avoids glomming the windows and appears as separate instances on taskbar. Any more context/details behind your scenario would be super helpful!

I think even if app windows are either gloomed or not, each window should be allowed to show their own badge to notify user that specific window needs their attention not pass the burden to user to find out which window needs their attention. The scenarios I can think of are:

1. Suppose you are designing a tabbed editor app that user uses to edit files in separate tabs. You might want to give user the flexibility to have multiple windows/instances of your app and have multiple tabs in them. You might want to notify the number of tabs that have unsaved changes separately for each window via taskbar badges so user knows which window they have to click and save there changes then. Also, the new Windows Terminal, IDEs come in this category.

2. Another scenario can be a social media app that lets user to use multiple accounts simultaneously (since most users normally have to social accounts: one for personal use, and one for official/ commercial use to separate their work from personal opinions or life stuff). You might want to each window to have their separate badges to notify users which account needs their attention.

[andrewleader]

Makes sense, thank you for all those details! That indeed does make sense. We'll discuss this with the taskbar UI team to see if they've heard similar user feedback about this, but I totally agree that the enhanced per-window badges would be useful for those cases!

[FrayxRulez]

Something that I'd love to see added to the badge API, would be the ability to flash the taskbar icon for the app as well.
This is a highly requested feature for IM apps and it would be great to have it (Or at least to be able to invoke FlashWindowEx for UWP apps, of course)

[Felix-Dev]

Something that I'd love to see added to the badge API, would be the ability to flash the taskbar icon for the app as well.
This is a highly requested feature for IM apps and it would be great to have it (Or at least to be able to invoke FlashWindowEx for UWP apps, of course)

App taskbar button flashing, as implemented now in Windows, comes with the following - to me - negative UX:

Another point about taskbar flashing: If you have enabled "automatically hiding the taskbar" in Windows Settings, taskbar flashing will block the taskbar from shrinking back until you've opened the app. In other words, it basically forces you to open the app as soon as possible. Now, in some cases that might be useful but not in others. Take Visual Studio for example. When you start VS by loading a project and then minimize it, VS will flash the taskbar once it's done loading the project and "ready to go":

While that's all fine and good, VS's taskbar icon now blocks my taskbar from automatically hiding again. It will now constantly occupy screen real-estate until I've opened VS - which could be in this moment or 5 minutes later. The user might not always want to jump into VS as soon as it is done loading. However, thanks to preventing the taskbar from hiding now, the user is quite forced to open the VS instance and minimize it again if the user is not ready to use it yet,

This is part of a longer exchange in another Project Reunion thread starting here. In addition to this, users have control over whether Windows 10 toast notifications or badges are shown in Windows, yet taskbar app button flashing cannot be turned off right now. So if a developer uses that as a way to raise attention, then users "have to live with it", no matter if they like taskbar app button flashing or not.

Ideally, the UWP shell notification APIs (Badge APIs, Toast notification APIs,...) will be improved so that developers who currently feel the need to use taskbar app button flashing instead can switch over to those notification shell elements. Taskbar app button flashing (as currently implemented) has the potential to be intrusive and obstructive to a user's current workflow.

[SetTrend]

Just like to bring this thread back to attention.

[andrewleader]

Hi @SetTrend, thanks for bringing this back up. This isn't part of our 1.1 plans and we're now tracking feature requests on our productboard portal, here's the feature request for badge APIs, please vote on it so we can easily inform you of updates via email!

Since we're tracking the feature there, I'll close this issue (although feel free to continue discussing).

And for flashing or progress indicators, feel free to submit that idea on productboard too and explain specifically what you'd need! If that becomes a popular request, we'll add that to the portal too so others can easily vote on it!

[michael-hawker]

@andrewleader left this feedback on Twitter here for @aclinick. I think it's important to have an issue open and linked to each product board item to facilitate community discussions and clarification on scope of features for specs and things like this issue does.

Closing it before the feature is done doesn't seem helpful and confusing. It also makes it harder for folks to find when searching issues on GitHub meaning they may file duplicate issues or not find a link to the product board to upvote the feature. (In general, it also means there's votes now in multiple places to coordinate.)

[andrewleader]

For this feature, we're not at the stage where we're scoping the feature specs yet - we don't know what specifically we'll build, or if there's enough interest to build this yet. When we get closer to specing out the feature we'll re-create a GitHub spec with more details.

By having people vote and explain what they need will allow us to look through what everyone's requirements are when we do get around to actually spec'ing the feature. Having all of that feedback go into productboard is simply easier for us (then regardless of whether a customer emails us feedback or votes through the portal, we can merge all of that feedback into a single place to see and understand what customers need).

One problem that happens here is thumbs up votes here on GitHub are tough to infer any meaning from. We can see that MarcAnt upvoted the proposal, but the proposal does mention custom icons... does MarcAnt need custom icons and that's why they upvoted the proposal? With our portal, we require them to say at least something when voting, which usually results in them giving some explanation of what they need and why.

[michael-hawker]

@andrewleader I guess I see the comments on the issue as the feedback when voting you mention in the product board. I guess the issue I see with the product board is that as a community member I don't see those comments and input other are providing you into what they see in that feature. Also, if there's just a one sentence descriptor of that feature, there's no way for me to ask questions about it or what the feature does or the scope that feature would provide compared to having an open issue or discussion here on GitHub to facilitate that.

[andrewleader]

The prompt on the portal asks users to explain "Why do you need this?", if they're unclear about what's in scope of the feature, they can explain "I need to do X, Y, and Z", and when we're building the feature we're able to evaluate everything that everyone needs. When our portal descriptions are vague and open ended, we try to include a call to action specifying "Tell us exactly what you need" to reinforce that they should tell us what they need. Additionally, another thing I hope our team does is once we do start spec'ing a feature, reach out to everyone that asked for the feature (which is a simple one-step action to notify everyone) and ask them to look over the spec and provide feedback.

We understand that this is a change and different, however the Adaptive Cards team has found great success with using the productboard portal, and we've already had over 380 votes come in through our portal in this short timespan (Adaptive Cards also saw a drastic increase in feedback when they started using their portal). We haven't seen anywhere near that engagement with just GitHub itself, and each of those votes typically has a short explanation of how they'd use the feature or what they need or why they need it, which we rarely get with GitHub. That explanation, along with having to rank features as "Critical" or "Important" or "Nice to have" drastically helps us prioritize and figure out what we should build and why.

Also, if users do ask clarifying questions when voting on the portal, we can respond directly to them. If we identify there's something ambiguous we should clarify in the description, we can then update the description.

Having an open GitHub issue when we're still just in the feedback and interest gathering stage of a feature would just add yet another place for feedback and votes to go to, which wouldn't be easily consolidated and therefore potentially ignored (we can manually sideload in the feedback from GitHub, but it's extra work for us, and then if they also vote on the portal their vote would potentially be double-counted depending on their GitHub username vs their email address).

[SetTrend]

One problem that happens here is thumbs up votes here on GitHub are tough to infer any meaning from.

From my own experience I can confirm this is an issue indeed.

[michael-hawker]

Thanks for the explanation @andrewleader, it's great to see your team getting more engagement and feedback there.

I think my main concern is the lack of transparency and connection to the community as none of the comments or new suggestions are exposed for others to chime-in on or be aware of.

Also, if you have developers already here on GitHub which are engaged; how do they know finding this closed issue to go vote for the feature on the product board?