Skip to content

Latest commit

 

History

History
123 lines (93 loc) · 5.02 KB

implementation.md

File metadata and controls

123 lines (93 loc) · 5.02 KB
Raw

Badge implementation on host platforms

This document describes a possible treatment on each major OS. User agents are free to implement however they like, but this should give an idea of what the API will look like in practice.

Table of Contents

macOS

Requires macOS 10.5 or higher.

  • The host API is a string, truncated from the center to a system-defined length, as shown/described here. The API is NSDockTile.setBadgeLabel.
  • Flag badges are passed as an empty string to setBadgeLabel (if that works, otherwise pass a space character). This shows an empty red circle.
  • Integer badges are saturated to 3 or 4 digits (with a "+" if overflowing), and passed as a string to setBadgeLabel.

Universal Windows Platform

Requires Windows 10 or higher, and requires that the user agent be a "UWP" app. Note that Google Chrome and Mozilla Firefox do not fall into this category, and hence don't have access to the necessary APIs.

  • The host API is BadgeNotification, which allows either a positive integer (saturated at 99) or a fixed glyph (shown here).
  • Integer badges are just passed straight through into this API.
  • Flag badges are passed as a fixed glyph, perhaps "attention", since I don't think there is a way to show an empty circle.

This will show up on both the Taskbar and Start Menu tile.

Legacy Windows (Win32)

Requires Windows 7 or higher.

  • The host API is ITaskbarList3::SetOverlayIcon, which allows applications to set a 16x16-pixel overlay icon in the corner of the application's main icon in the Taskbar.
  • Due to the nature of being a 16x16-pixel icon, the user agent must render the text or number into an image. It pretty much has to be 1–2 characters.
  • Flag badges are just passed as a coloured circle.
  • Integer badges are rendered as the number, if a single digit, or "+", if greater than 9.

Note: This API only allows badging a currently open window.

Android

Requires Android 8.0 (Oreo) or higher.

  • The host API is NotificationChannel, which lets you set a number only. The badge is usually shown as a coloured dot; the number is only shown on a long-press (at least in the Pixel home screen).
  • Tricky: The API is tied to notifications. You can't show a badge unless there are pending notifications.

Chrome OS

Not currently supported, but will soon be available for Android apps using the above NotificationChannel API. The Chrome browser itself will be able to re-use the same UI for showing a coloured dot in response to the Badge API.

iOS

  • The host API is UIApplication.applicationIconBadgeNumber, which lets you set a positive integer only.
  • Integer badges are passed directly to the host API.
  • Flag badges and strings other than digits are just represented by the number "1".
  • Warning: A potential issue on iOS is the sentence in this document: "Note that reducing a badge’s count to zero removes all related notifications from Notification Center." This suggests a possibly unwanted interaction between the Badge API and notifications on iOS (implying that web developers can't use badges to show state that is unrelated to notifications, because it might dismiss the notification).

Ubuntu

Requires Ubuntu (no general API for Linux).

  • The host API is unity_launcher_*, which lets you set an integer only.
  • Badges have the same restrictions as iOS.

Summary

  • All known host OSes support some form of badge.
  • Integer badges are always supported (but sometimes reduced to a simple dot).
  • Most platforms support showing at least one arbitrary character. UWP limits to a small selection of glyphs. iOS and Ubuntu can only show numbers.

Thus, a fallback option for platforms that do not support arbitrary characters (e.g., choose whether to show a number, or nothing) may be necessary.