ServiceWorkerRegistration.getNotifications() — Methode · JavaScript-Referenz

Signatur

ServiceWorkerRegistration.prototype.getNotifications(options)

Beschreibung

Die Methode getNotifications() der Schnittstelle ServiceWorkerRegistration gibt die Benachrichtigungen zurück, die die aktuelle Herkunft (Origin) über die aktuelle Service-Worker-Registrierung erstellt hat und die noch sichtbar sind, also weder geschlossen noch vom Nutzer weggeklickt wurden. Die Reihenfolge entspricht der Reihenfolge, in der sie erstellt wurden.

Gebraucht wird die Methode vor allem bei Push-Benachrichtigungen. Man kann damit alte Meldungen zusammenfassen („3 neue Nachrichten“ statt drei Einzelmeldungen), veraltete Benachrichtigungen gezielt mit notification.close() schließen, etwa wenn der Nutzer den Inhalt schon in einem anderen Tab gelesen hat, oder zählen, wie viele Meldungen gerade offen sind.

Mit dem optionalen Filter { tag } bekommt man nur die Benachrichtigungen mit genau diesem tag. Zusammen mit dem tag-Feld aus showNotification() lassen sich so Benachrichtigungen nach Thema gruppieren, zum Beispiel pro Chat-Unterhaltung.

Die Methode steht sowohl im Fenster-Kontext (über navigator.serviceWorker.ready) als auch im Service Worker selbst (über self.registration) zur Verfügung.

Parameter

Name	Typ	Default	Beschreibung
$options	Object	{}	Optionales Filterobjekt.
$options.tag	string	""	Gibt nur Benachrichtigungen mit genau diesem `tag` zurück. Ein leerer String oder ein fehlender Wert bedeutet: kein Filter.

Rückgabewert

Typ

Promise<Notification[]>

Beschreibung

Ein Promise, das mit einem Array von Notification-Objekten erfüllt wird. Das Array ist leer, wenn keine passenden Benachrichtigungen mehr angezeigt werden.

Beispiele

Offene Benachrichtigungen im Fenster-Kontext zählen

const zaehleBenachrichtigungen = async () => {
  const registration = await navigator.serviceWorker.ready;
  const notifications = await registration.getNotifications();
  console.log(`Offene Benachrichtigungen: ${notifications.length}`);
  notifications.forEach((n) => console.log(n.title, n.tag));
};

zaehleBenachrichtigungen();

Offene Benachrichtigungen: 2 Neue Nachricht chat-42 Update verfügbar system

Push-Nachrichten im Service Worker zusammenfassen

// sw.js
self.addEventListener('push', (event) => {
  const data = event.data?.json() ?? {};
  const tag = `chat-${data.chatId}`;

  event.waitUntil((async () => {
    const vorhandene = await self.registration.getNotifications({ tag });
    const anzahl = vorhandene.length > 0
      ? (vorhandene[0].data?.anzahl ?? 1) + 1
      : 1;

    // Gleicher tag ersetzt die alte Benachrichtigung
    await self.registration.showNotification(
      anzahl > 1 ? `${anzahl} neue Nachrichten` : 'Neue Nachricht',
      {
        body: data.text,
        tag,
        renotify: true,
        data: { anzahl }
      }
    );
  })());
});

Veraltete Benachrichtigungen nach dem Lesen schließen

const schliesseChatBenachrichtigungen = async (chatId) => {
  const registration = await navigator.serviceWorker.ready;
  const notifications = await registration.getNotifications({ tag: `chat-${chatId}` });
  notifications.forEach((n) => n.close());
  console.log(`${notifications.length} Benachrichtigung(en) geschlossen`);
};

// z. B. beim Öffnen der Unterhaltung
schliesseChatBenachrichtigungen(42);

1 Benachrichtigung(en) geschlossen

// Wichtig · Fallstricke

Zurückgegeben werden nur Benachrichtigungen, die über ServiceWorkerRegistration.showNotification() für genau diese Registrierung erstellt wurden. Mit new Notification() im Fenster erzeugte Meldungen tauchen hier nicht auf.
Ohne erteilte Berechtigung (Notification.permission !== 'granted') ist das Ergebnis ein leeres Array.
Manche Browser und Betriebssysteme melden Benachrichtigungen, die der Nutzer im Benachrichtigungszentrum des Systems gelöscht hat, nicht zuverlässig. Deshalb sollte man sich nicht darauf verlassen, dass die Liste exakt stimmt.
Der tag-Filter vergleicht exakt. Präfixe oder Platzhalter funktionieren nicht, dafür muss man ohne Filter abfragen und das Array danach selbst filtern.
Im Service Worker gehört die Abfrage in event.waitUntil(), sonst kann der Worker beendet werden, bevor das Promise erfüllt ist.
Benötigt einen sicheren Kontext (HTTPS oder localhost). Unter iOS/iPadOS funktioniert die Methode erst ab 16.4 und nur für Web-Apps, die zum Home-Bildschirm hinzugefügt wurden.

Siehe auch

Notification Notification.close() ServiceWorkerRegistration.showNotification() ServiceWorkerRegistration.unregister() ServiceWorkerRegistration.update()