PushSubscriptionOptions.userVisibleOnly — Eigenschaft · JavaScript-Referenz

Signatur

PushSubscriptionOptions.userVisibleOnly

Beschreibung

Die schreibgeschützte Eigenschaft userVisibleOnly des Interfaces PushSubscriptionOptions zeigt, mit welcher Zusage ein Push-Abonnement angelegt wurde. Ist sie true, hat die Anwendung versprochen, bei jeder eingehenden Push-Nachricht etwas für den Nutzer Sichtbares auszulösen, meist über ServiceWorkerRegistration.showNotification().

Man erreicht das Objekt über PushSubscription.options. Der Wert entspricht dem, was beim Aufruf von PushManager.subscribe({ userVisibleOnly, applicationServerKey }) übergeben wurde. Mit der Eigenschaft lässt sich prüfen, ob ein vorhandenes Abonnement zu den aktuellen Anforderungen der App passt, oder man kann den Zustand zu Diagnosezwecken ans Backend schicken.

In der Praxis ist der Wert fast immer true. Die großen Browser (Chrome, Edge, Safari) lehnen stille Push-Abonnements mit userVisibleOnly: false ab. Stiller Hintergrund-Push, bei dem der Nutzer nichts bemerkt, ist im Web also kaum nutzbar.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Abonnement nur für Nachrichten gilt, die für den Nutzer sichtbar sind. Sonst false (Standardwert beim Abonnieren).

Beispiele

Vorhandenes Abonnement prüfen

const checkSubscription = async () => {
  const registration = await navigator.serviceWorker.ready;
  const subscription = await registration.pushManager.getSubscription();

  if (!subscription) {
    console.log('Kein Push-Abonnement vorhanden');
    return;
  }

  console.log('userVisibleOnly:', subscription.options.userVisibleOnly);
};

checkSubscription();

userVisibleOnly: true

Abonnieren und Option kontrollieren

// VAPID-Public-Key (Base64URL) in Uint8Array umwandeln
const urlBase64ToUint8Array = (base64) => {
  const padding = '='.repeat((4 - (base64.length % 4)) % 4);
  const raw = atob((base64 + padding).replace(/-/g, '+').replace(/_/g, '/'));
  return Uint8Array.from(raw, (c) => c.charCodeAt(0));
};

const subscribe = async (vapidKey) => {
  const registration = await navigator.serviceWorker.register('/sw.js');
  await navigator.serviceWorker.ready;

  const subscription = await registration.pushManager.subscribe({
    userVisibleOnly: true,
    applicationServerKey: urlBase64ToUint8Array(vapidKey)
  });

  const { userVisibleOnly } = subscription.options;
  console.log(`Abonniert, sichtbar: ${userVisibleOnly}`);
  return subscription;
};

Abonniert, sichtbar: true

Veraltetes Abonnement erneuern

const ensureVisibleSubscription = async (applicationServerKey) => {
  const registration = await navigator.serviceWorker.ready;
  let subscription = await registration.pushManager.getSubscription();

  // Ein Abonnement ohne passende Zusage kündigen und neu anlegen
  if (subscription && !subscription.options.userVisibleOnly) {
    await subscription.unsubscribe();
    subscription = null;
  }

  subscription ??= await registration.pushManager.subscribe({
    userVisibleOnly: true,
    applicationServerKey
  });

  await fetch('/api/push/subscribe', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(subscription)
  });
};

Zusage im Service Worker einhalten (sw.js)

// Bei userVisibleOnly: true muss jede Push-Nachricht sichtbar werden
self.addEventListener('push', (event) => {
  const data = event.data?.json() ?? { title: 'Neuigkeit', body: '' };
  event.waitUntil(
    self.registration.showNotification(data.title, { body: data.body })
  );
});

// Wichtig · Fallstricke

Nur lesbar: Eine Zuweisung an userVisibleOnly hat keine Wirkung. Um den Wert zu ändern, muss man das Abonnement mit unsubscribe() kündigen und neu abonnieren.
false wird meist abgelehnt: Chrome, Edge und Safari weisen subscribe({ userVisibleOnly: false }) mit einem NotAllowedError zurück. Firefox erlaubt es, begrenzt aber die Zahl der stillen Push-Nachrichten.
Zusage einhalten: Zeigt der Service Worker bei userVisibleOnly: true keine Benachrichtigung an, blendet Chrome eine allgemeine Meldung ein („Diese Website wurde im Hintergrund aktualisiert“). Andere Browser können das Abonnement dann auch widerrufen. showNotification() deshalb immer in event.waitUntil() einbetten.
Kompatibilität: Das Objekt PushSubscription.options gibt es noch nicht so lange wie die Push-API selbst. In älteren Browsern vorher mit subscription.options?.userVisibleOnly prüfen. Die Eigenschaft funktioniert nur in einem sicheren Kontext (HTTPS) und mit einem registrierten Service Worker. Auf iOS/iPadOS geht Push erst ab 16.4 und nur für Web-Apps, die zum Home-Bildschirm hinzugefügt wurden.

Siehe auch

PushSubscriptionOptions.applicationServerKey PushSubscription.options PushSubscription.subscriptionId PushSubscription.endpoint PushSubscription.expirationTime