ServiceWorkerGlobalScope: notificationclick — Ereignis · JavaScript-Referenz

Signatur

self.addEventListener("notificationclick", (event) => { … })

Beschreibung

Das Ereignis notificationclick tritt im globalen Gültigkeitsbereich eines Service Workers (ServiceWorkerGlobalScope) auf. Es wird ausgelöst, sobald jemand auf eine persistente Benachrichtigung klickt, die mit ServiceWorkerRegistration.showNotification() erstellt wurde. Das gilt auch dann, wenn die Seite selbst gar nicht mehr geöffnet ist. Deshalb ist das Ereignis der zentrale Baustein für Push-Benachrichtigungen: Erst hier entscheidet sich, was nach einem Klick passiert.

Der Handler bekommt ein NotificationEvent. Über event.notification erreichst du die angeklickte Notification mit title, tag, data und weiteren Werten. Wurde ein Aktionsknopf angeklickt (definiert über die Option actions), enthält event.action dessen action-Kennung. Bei einem Klick auf den Körper der Benachrichtigung ist der Wert ein leerer String.

Typische Aufgaben im Handler:

die Benachrichtigung mit event.notification.close() schließen,
über clients.matchAll() ein schon offenes Fenster suchen und mit client.focus() in den Vordergrund holen,
andernfalls mit clients.openWindow(url) ein neues Fenster öffnen,
asynchrone Arbeit mit event.waitUntil() absichern, damit der Browser den Service Worker nicht vorzeitig beendet.

Du kannst den Handler alternativ über die Eigenschaft self.onnotificationclick = (event) => { … } setzen. Mit addEventListener sind aber mehrere Handler möglich, und sie lassen sich mit removeEventListener wieder entfernen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"notificationclick"`.
$listener Pflicht	(event: NotificationEvent) => void		Handler-Funktion, die ein `NotificationEvent` erhält. Wichtige Eigenschaften: `event.notification` (die angeklickte `Notification`) und `event.action` (Kennung des angeklickten Aktionsknopfs oder `""`). Wichtige Methode: `event.waitUntil(promise)`.
$options	boolean\|AddEventListenerOptions	false	Übliche Optionen von `addEventListener`, z. B. `{ once: true }`.

Rückgabewert

Typ

void

Beschreibung

addEventListener hat keinen Rückgabewert. Die Wirkung entsteht über die Seiteneffekte im Handler (Fenster fokussieren oder öffnen, Benachrichtigung schließen).

Beispiele

Vorhandenes Fenster fokussieren oder neues öffnen

// sw.js
self.addEventListener('notificationclick', (event) => {
  event.notification.close();
  const targetUrl = new URL(event.notification.data?.url ?? '/', self.location.origin).href;

  event.waitUntil((async () => {
    const windows = await clients.matchAll({ type: 'window', includeUncontrolled: true });
    const existing = windows.find((c) => c.url === targetUrl);
    if (existing) {
      return existing.focus();
    }
    return clients.openWindow(targetUrl);
  })());
});

Aktionsknöpfe auswerten

// Seite: Benachrichtigung mit Aktionen anzeigen
const reg = await navigator.serviceWorker.ready;
await reg.showNotification('Neue Nachricht von Anna', {
  body: 'Hast du heute Zeit?',
  tag: 'chat-42',
  data: { chatId: 42 },
  actions: [
    { action: 'reply', title: 'Antworten' },
    { action: 'mute', title: 'Stummschalten' }
  ]
});

// sw.js
self.addEventListener('notificationclick', (event) => {
  const { chatId } = event.notification.data;
  event.notification.close();

  if (event.action === 'mute') {
    event.waitUntil(fetch(`/api/chats/${chatId}/mute`, { method: 'POST' }));
  } else if (event.action === 'reply') {
    event.waitUntil(clients.openWindow(`/chat/${chatId}?reply=1`));
  } else {
    // Klick auf den Körper der Benachrichtigung
    event.waitUntil(clients.openWindow(`/chat/${chatId}`));
  }
});

on-Property und removeEventListener

// sw.js — Variante über die Handler-Eigenschaft
self.onnotificationclick = (event) => {
  console.log('Angeklickt:', event.notification.tag, 'Aktion:', event.action || '(keine)');
  event.notification.close();
};

// Variante mit benanntem Handler, der sich entfernen lässt
const handleClick = (event) => {
  event.notification.close();
  event.waitUntil(clients.openWindow('/'));
};
self.addEventListener('notificationclick', handleClick);
// später, z. B. nach einer Konfigurationsänderung:
self.removeEventListener('notificationclick', handleClick);

Angeklickt: chat-42 Aktion: (keine)

// Wichtig · Fallstricke

Immer event.waitUntil() nutzen: Ohne diesen Aufruf kann der Browser den Service Worker beenden, bevor openWindow() oder fetch() fertig ist.
clients.openWindow() und client.focus() funktionieren nur, solange die Nutzerinteraktion noch gilt. Sie müssen also während des Handlers bzw. innerhalb von waitUntil aufgerufen werden, sonst lehnt der Browser sie ab. Außerdem gibt es ein Zeitlimit (in Chrome wenige Sekunden). Lange Netzwerkanfragen vor dem Öffnen solltest du vermeiden.
Die Benachrichtigung schließt nicht automatisch: Auf vielen Plattformen bleibt sie nach dem Klick sichtbar, bis du event.notification.close() aufrufst.
Das Ereignis gilt nur für persistente Benachrichtigungen aus showNotification(). Bei new Notification() im Fenster benutzt du stattdessen notification.onclick.
Das Schließen ohne Klick (Wegwischen) löst notificationclose aus, nicht notificationclick.
Kompatibilität: Aktionsknöpfe (actions, event.action) unterstützen weder Firefox noch Safari. In Safari (iOS/iPadOS 16.4+) gibt es Web-Push nur für Web-Apps, die zum Home-Bildschirm hinzugefügt wurden. Prüfe die Anzahl möglicher Aktionen mit Notification.maxActions.
Sicherheit: URLs aus notification.data (die oft aus Push-Nachrichten stammen) solltest du prüfen. Öffne am besten nur Adressen des eigenen Ursprungs, damit niemand die Benachrichtigung für eine offene Weiterleitung (Open Redirect) missbrauchen kann.

Siehe auch

ServiceWorkerGlobalScope: notificationclose ServiceWorkerGlobalScope: activate ServiceWorkerGlobalScope: periodicsync ServiceWorkerGlobalScope: contentdelete ServiceWorkerGlobalScope: cookiechange ServiceWorkerGlobalScope: pushsubscriptionchange