This specification defines an API that allows [=installed web applications=] to set an application badge, which is usually shown alongside the application's icon on the device's home screen or application dock.
This is a work in progress.
async function updateMailBadge() {
// Check if the API is supported.
if (!navigator.setAppBadge) return;
const unreadCount = await getUnreadMailCount();
// Try to set the app badge.
try {
await navigator.setAppBadge(unreadCount);
} catch (e) {
// The badge is not supported, or the user has prevented the app
// from setting a badge.
}
}
The badge might show up on the application's icon in the operating system. If multiple API calls within the same application [=badge/set=] or [=badge/clear=] a badge, the most recent one takes effect, and may continue being seen even after an application is closed.
async function showPlayerTurn(playerTurnId) {
if (playerTurnId === localPlayerId)
await navigator.setAppBadge();
else
await navigator.clearAppBadge();
}
On some operating systems [=badge/setting=] a badge can require permission from the user. In this case, a developer need to query the "[=notifications=]" permissions status before [=badge/setting=] a badge. If the permission is not granted, the developer will need to prompt for permission via the {{Notification}}.{{Notification/requestPermission()}}.
async function checkPermission() {
permission = await navigator.permissions.query({
name: "notifications",
});
const button = document.getElementById("permission-button");
if (permission.state === "prompt") {
// Prompt the user to grant permission.
button.hidden = false;
button.addEventListener("click", async () => {
await Notification.requestPermission();
checkPermission();
}, { once: true });
return;
}
button.hidden = true;
}
A badge is intended as a mechanism for [=installed web applications=] to notify the user that there is some new activity that might require their attention, or as a way of indicating a small amount of information, such as an unread count.
A [=badge=] can have one of the following values:
An [=installed web application=] has an associated [=badge=], which is initialized to [="nothing"=].
The user agent MAY (re)[=set=] an application's badge to [="nothing"=] at its discretion (for example, following system conventions).
When the application's badge is set, the [=user agent=] or operating system SHOULD display the application's [=badge=] alongside the primary iconic representation of the application in the user's operating system (for example, as a small overlay on top of the application's icon on the home screen on a device).
A user agent MAY require [=express permission=] from the user to [=badge/set=] the badge. When a user agent requires such [=permission=], it SHOULD tie the permission grant to the "[=notifications=]" permission.
When the [=badge=] is [=badge/set=] to [="flag"=], the [=user agent=] or operating system SHOULD display an indicator with a non-specific symbol (for example, a colored circle).
When a [=badge=]'s value is [=badge/set=] to [="nothing"=], the [=user agent=] or operating system SHOULD clear the [=badge=] by no longer displaying it.
When the [=badge=] is [=badge/set=] to a [=number=], the [=user agent=] or operating system:
[SecureContext]
interface mixin NavigatorBadge {
Promise<undefined> setAppBadge(
optional [EnforceRange] unsigned long long contents
);
Promise<undefined> clearAppBadge();
};
Navigator includes NavigatorBadge;
WorkerNavigator includes NavigatorBadge;
User agents that never display application badges SHOULD NOT [=interface/include=] {{NavigatorBadge}}.
When the {{NavigatorBadge/setAppBadge()}} method is called, the user agent MUST [=set the application badge=] of [=this=] to value of the |contents:unsigned long long| argument.
When the {{NavigatorBadge/clearAppBadge()}} method is called, the user agent MUST [=set the application badge=] of [=this=] to 0.
To set the application badge of platform object |context:platform object| to an optional {{unsigned long long}} |contents:unsigned long long| value:
The API is write-only by design. There is no way for a site to read back the value of a badge that was previously set, to ensure that the application badge cannot be used as a storage or fingerprinting mechanism.
The [=user agent=] or operating system MAY [=badge/clear=] a [=badge=] at its discretion, and to follow any system conventions (for example, when the system is reset).