Navigator.setAppBadge() — Methode · JavaScript-Referenz

Signatur

Navigator.prototype.setAppBadge(contents)

Beschreibung

Die Methode navigator.setAppBadge() gehört zur Badging API. Mit ihr zeigt eine installierte Progressive Web App (PWA) auf ihrem App-Symbol ein Abzeichen an, etwa in der Taskleiste, im Dock oder auf dem Home-Bildschirm. Typische Anwendungsfälle sind Zähler für ungelesene Nachrichten, offene Aufgaben oder neue Benachrichtigungen. Das ist deutlich unaufdringlicher als eine Push-Benachrichtigung.

Wird eine positive Ganzzahl übergeben, zeigt das Betriebssystem diese Zahl an (manche Plattformen kürzen große Werte, z. B. auf „99+“). Ruft man die Methode ohne Argument auf, erscheint ein neutrales „Flag“-Abzeichen, meist ein Punkt. Der Wert 0 entfernt das Abzeichen, das entspricht einem Aufruf von navigator.clearAppBadge().

Die Methode steht sowohl im Fenster-Kontext als auch in Workern zur Verfügung (WorkerNavigator.setAppBadge()). So kann auch ein Service Worker das Abzeichen aktualisieren, etwa beim Empfang einer Push-Nachricht, während die App geschlossen ist. Die Methode liefert ein Promise zurück und sollte deshalb mit await oder .catch() verwendet werden.

Parameter

Name	Typ	Default	Beschreibung
$contents	number	undefined (Flag-Abzeichen)	Nicht-negative Ganzzahl, die als Abzeichen angezeigt wird. Ohne Angabe erscheint ein Punkt- bzw. Flag-Abzeichen, bei `0` wird das Abzeichen entfernt. Negative Werte oder Werte über `Number.MAX_SAFE_INTEGER` führen zu einem `TypeError`.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald das Abzeichen gesetzt ist. Es wird mit einem NotAllowedError (DOMException) abgelehnt, wenn das Dokument nicht vollständig aktiv ist oder die Berechtigung fehlt. Bei ungültigen Werten wird ein TypeError ausgelöst.

Beispiele

Zähler ungelesener Nachrichten mit Feature-Erkennung

const updateBadge = async (unreadCount) => {
  if (!('setAppBadge' in navigator)) {
    console.log('Badging API wird nicht unterstützt');
    return;
  }
  try {
    if (unreadCount > 0) {
      await navigator.setAppBadge(unreadCount);
    } else {
      await navigator.clearAppBadge();
    }
    console.log(`Badge aktualisiert: ${unreadCount}`);
  } catch (err) {
    console.error('Badge konnte nicht gesetzt werden:', err.name);
  }
};

updateBadge(5);

Badge aktualisiert: 5

Neutrales Hinweis-Abzeichen ohne Zahl

// Zeigt nur einen Punkt, z. B. wenn neue Inhalte verfügbar sind
const markNewContent = async () => {
  if ('setAppBadge' in navigator) {
    await navigator.setAppBadge();
    console.log('Hinweis-Punkt gesetzt');
  }
};

markNewContent();

Hinweis-Punkt gesetzt

Badge aus dem Service Worker bei einer Push-Nachricht setzen

// sw.js
self.addEventListener('push', (event) => {
  const data = event.data?.json() ?? {};
  const count = Number(data.unread ?? 0);

  event.waitUntil((async () => {
    if ('setAppBadge' in self.navigator) {
      await self.navigator.setAppBadge(count);
    }
    await self.registration.showNotification('Neue Nachricht', {
      body: `Du hast ${count} ungelesene Nachrichten.`
    });
  })());
});

Badge beim Wechsel zurück in die App entfernen

document.addEventListener('visibilitychange', async () => {
  if (document.visibilityState === 'visible' && 'clearAppBadge' in navigator) {
    await navigator.clearAppBadge();
    console.log('Badge entfernt');
  }
});

Badge entfernt

// Wichtig · Fallstricke

Browser-Kompatibilität: Unterstützt in Chromium-Browsern (Chrome, Edge) auf Windows, macOS und ChromeOS sowie in Safari 16.4+ auf iOS/iPadOS (nur für zum Home-Bildschirm hinzugefügte Web-Apps) und in Safari 17+ unter macOS 14. Firefox unterstützt die API nicht. Deshalb immer mit 'setAppBadge' in navigator prüfen.
Nur installierte Apps: In einem normalen Browser-Tab bleibt der Aufruf meist ohne sichtbare Wirkung. Das Abzeichen erscheint nur, wenn die Seite als PWA installiert ist.
Nur sicherer Kontext: Die Methode ist nur über HTTPS (oder localhost) verfügbar.
Berechtigungen: Unter iOS/iPadOS muss der Nutzer Benachrichtigungen erlauben (Notification.requestPermission()), sonst wird kein Abzeichen angezeigt. Unter Android übernimmt Chrome die Zahl nicht, dort zeigt das System höchstens einen Punkt an, wenn Benachrichtigungen aktiv sind.
Darstellung ist Sache des Betriebssystems: Ob eine Zahl, ein gekürzter Wert („99+“) oder nur ein Punkt erscheint, entscheidet die Plattform. Verlasse dich also nicht auf eine exakte Darstellung.
Das Abzeichen ist keine Benachrichtigung. Es bleibt bestehen, bis es überschrieben oder mit clearAppBadge() bzw. setAppBadge(0) entfernt wird. Setze es daher nach dem Lesen aktiv zurück.

Siehe auch

Navigator.clearAppBadge() WorkerNavigator.setAppBadge() Navigator ServiceWorkerRegistration.showNotification() Notification.requestPermission() Navigator.javaEnabled()