Signatur
Beschreibung
setAppBadge() gehört zur Badging API und ist über navigator in Workern verfügbar – vor allem in Service Workern. Damit kann eine installierte Progressive Web App (PWA) ein kleines Abzeichen auf ihrem Icon in Taskleiste, Dock oder Startbildschirm anzeigen, ohne dass ein Fenster der App geöffnet sein muss.
Typischer Einsatz: Im push-Event eines Service Workers geht eine neue Nachricht ein, und der Zähler ungelesener Elemente wird direkt auf dem App-Icon aktualisiert. Übergibt man eine Zahl, zeigt das Betriebssystem diese an; ohne Argument erscheint eine allgemeine Markierung (meist ein Punkt). Der Wert 0 wirkt wie clearAppBadge() und entfernt das Abzeichen.
Wie das Abzeichen konkret aussieht, entscheidet das Betriebssystem: große Zahlen werden ggf. abgekürzt (z. B. „99+“), manche Plattformen zeigen nur einen Punkt. Die Methode funktioniert in der Regel nur für installierte Web-Apps in einem sicheren Kontext (HTTPS).
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $contents | number | Optionale, nicht-negative ganze Zahl, die als Abzeichen angezeigt wird. Fehlt sie, wird ein allgemeines Markierungs-Abzeichen gesetzt. 0 entfernt das Abzeichen. Werte werden in unsigned long long umgewandelt; negative Zahlen oder NaN führen zu einem TypeError. |
Rückgabewert
undefined erfüllt wird, sobald das Abzeichen gesetzt wurde. Es wird z. B. mit NotAllowedError abgelehnt, wenn die App nicht berechtigt ist, oder mit TypeError bei ungültigem Wert.Beispiele
Ungelesene Nachrichten im push-Event anzeigen
// service-worker.js
self.addEventListener('push', (event) => {
const data = event.data?.json() ?? {};
const unread = Number(data.unreadCount ?? 0);
event.waitUntil((async () => {
await self.registration.showNotification('Neue Nachricht', {
body: data.text ?? 'Du hast eine neue Nachricht.'
});
if ('setAppBadge' in navigator) {
await navigator.setAppBadge(unread);
}
})());
});Allgemeine Markierung ohne Zahl setzen
// Im Service Worker: signalisiert „es gibt etwas Neues“
const markAsUpdated = async () => {
if (!('setAppBadge' in navigator)) return;
try {
await navigator.setAppBadge(); // zeigt meist einen Punkt
console.log('Badge gesetzt');
} catch (err) {
console.warn('Badge konnte nicht gesetzt werden:', err.name);
}
};
self.addEventListener('sync', (event) => {
if (event.tag === 'check-updates') {
event.waitUntil(markAsUpdated());
}
});Badge zurücksetzen, wenn der Nutzer die Benachrichtigung anklickt
self.addEventListener('notificationclick', (event) => {
event.notification.close();
event.waitUntil((async () => {
// 0 entspricht clearAppBadge()
await navigator.setAppBadge?.(0);
const allClients = await clients.matchAll({ type: 'window' });
if (allClients.length > 0) {
await allClients[0].focus();
} else {
await clients.openWindow('/inbox');
}
})());
});// Wichtig · Fallstricke
- Browser-Unterstützung: Chromium-basierte Browser (Chrome, Edge) auf Windows, macOS und ChromeOS sowie Safari 16.4+ für Home-Screen-Web-Apps. Firefox unterstützt die Badging API nicht. Vor dem Aufruf immer per
'setAppBadge' in navigatorprüfen. - Funktioniert nur in sicheren Kontexten (HTTPS) und meist nur bei installierten PWAs. Auf Android setzt Chrome keine Zahlen-Abzeichen per API – dort erzeugt das System Punkte aus Benachrichtigungen.
- Auf iOS/iPadOS (Safari) muss die Nutzerin zusätzlich die Berechtigung für Benachrichtigungen erteilt haben (
Notification.requestPermission()), sonst hat der Aufruf keinen sichtbaren Effekt bzw. wird abgelehnt. - Im Service Worker den Aufruf in
event.waitUntil()einbetten, damit der Worker nicht vorzeitig beendet wird. - Negative Werte oder
NaNwerfen einenTypeError; die Darstellung großer Zahlen (z. B. „99+“) bestimmt das Betriebssystem.