PushSubscriptionOptions — Schnittstelle · JavaScript-Referenz

Signatur

interface PushSubscriptionOptions

Beschreibung

Die Schnittstelle PushSubscriptionOptions gehört zur Push-API. Sie beschreibt, mit welchen Optionen ein Push-Abonnement angelegt wurde. Eine Instanz bekommt man nie über einen Konstruktor, sondern nur über die Eigenschaft PushSubscription.options eines bestehenden Abonnements. Das Abonnement selbst entsteht mit PushManager.subscribe() oder wird mit PushManager.getSubscription() abgefragt.

Das Objekt hat zwei schreibgeschützte Eigenschaften:

userVisibleOnly (boolean): Gibt an, ob jede Push-Nachricht für den Nutzer sichtbar sein muss, meist als Benachrichtigung. Chrome akzeptiert nur true.
applicationServerKey (ArrayBuffer | null): Der öffentliche VAPID-Schlüssel des Anwendungsservers als rohe Bytes (P-256, unkomprimiert, 65 Byte). Der Push-Dienst prüft damit, ob Nachrichten wirklich vom eigenen Server stammen.

In der Praxis nutzt man die Schnittstelle vor allem, um ein vorhandenes Abonnement zu prüfen. Ein typischer Fall: Nach einem Wechsel des VAPID-Schlüssels vergleicht man applicationServerKey mit dem aktuellen Schlüssel. Stimmen sie nicht überein, meldet man das alte Abonnement ab und legt ein neues an.

Parameter

Name	Typ	Default	Beschreibung
$userVisibleOnly	boolean	false	Schreibgeschützte Eigenschaft: `true`, wenn jede Push-Nachricht eine sichtbare Benachrichtigung auslösen muss.
$applicationServerKey	ArrayBuffer \| null	null	Schreibgeschützte Eigenschaft: der öffentliche VAPID-Schlüssel des Anwendungsservers als `ArrayBuffer`, oder `null`, wenn keiner angegeben wurde.

Rückgabewert

Typ

PushSubscriptionOptions

Beschreibung

Wird über PushSubscription.options geliefert. Ein Objekt mit den schreibgeschützten Eigenschaften userVisibleOnly und applicationServerKey.

Beispiele

Abonnement anlegen und Optionen auslesen

// Hilfsfunktion: Base64URL-String 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 VAPID_PUBLIC_KEY = 'BEl62iUYgUivxIkv69yViEuiBIa-Ib9-SkvMeAtA3LFgDzkrxZJjSgSnfckjBJuBkr3qBUYIHBQFLXYp5Nksh8U';

const subscribe = async () => {
  const registration = await navigator.serviceWorker.register('/sw.js');
  const subscription = await registration.pushManager.subscribe({
    userVisibleOnly: true,
    applicationServerKey: urlBase64ToUint8Array(VAPID_PUBLIC_KEY)
  });

  const { options } = subscription; // PushSubscriptionOptions
  console.log(options.userVisibleOnly);
  console.log(options.applicationServerKey.byteLength);
};

subscribe();

true 65

Nach VAPID-Schlüsselwechsel neu abonnieren

const bufferToBase64Url = (buffer) =>
  btoa(String.fromCharCode(...new Uint8Array(buffer)))
    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');

const ensureCurrentKey = async (currentKeyBase64Url, keyBytes) => {
  const registration = await navigator.serviceWorker.ready;
  let subscription = await registration.pushManager.getSubscription();

  const storedKey = subscription?.options.applicationServerKey;
  const matches = storedKey && bufferToBase64Url(storedKey) === currentKeyBase64Url;

  if (subscription && !matches) {
    console.log('Veralteter Schlüssel – melde ab und neu an');
    await subscription.unsubscribe();
    subscription = null;
  }

  if (!subscription) {
    subscription = await registration.pushManager.subscribe({
      userVisibleOnly: true,
      applicationServerKey: keyBytes
    });
  }
  return subscription;
};

Veralteter Schlüssel – melde ab und neu an

Optionen für Debugging protokollieren

const logPushOptions = async () => {
  if (!('PushManager' in window)) {
    console.log('Push-API nicht unterstützt');
    return;
  }
  const registration = await navigator.serviceWorker.ready;
  const subscription = await registration.pushManager.getSubscription();
  if (!subscription) {
    console.log('Kein Abonnement vorhanden');
    return;
  }
  const { userVisibleOnly, applicationServerKey } = subscription.options;
  console.table({
    userVisibleOnly,
    hatServerKey: applicationServerKey !== null
  });
};

logPushOptions();

Kein Abonnement vorhanden

// Wichtig · Fallstricke

Kein Konstruktor: Ein PushSubscriptionOptions-Objekt lässt sich nicht selbst erzeugen. Man bekommt es nur über subscription.options. Die Eigenschaften sind schreibgeschützt. Um Optionen zu ändern, meldet man das Abonnement mit unsubscribe() ab und legt es mit subscribe() neu an.
Typ des Schlüssels: An subscribe() übergibt man den Schlüssel als Uint8Array oder als Base64URL-String. applicationServerKey liefert ihn aber immer als ArrayBuffer zurück. Vor einem Vergleich muss man ihn also umwandeln.
userVisibleOnly: Chromium-Browser lehnen userVisibleOnly: false ab. Safari verlangt ebenfalls sichtbare Benachrichtigungen. Wer im Service Worker bei einem push-Event keine Benachrichtigung anzeigt, riskiert, dass der Browser eine allgemeine Meldung zeigt oder das Abonnement entzieht.
Kompatibilität: Die Push-API braucht einen sicheren Kontext (HTTPS) und einen Service Worker. Firefox unterstützt die Eigenschaften von PushSubscriptionOptions erst ab Version 75. Safari auf iOS/iPadOS (ab 16.4) erlaubt Push nur für Web-Apps, die zum Home-Bildschirm hinzugefügt wurden.
Sicherheit: Nur der öffentliche VAPID-Schlüssel gehört in den Client. Der private Schlüssel bleibt ausschließlich auf dem Server.

Siehe auch

PushSubscription USBConfiguration UserActivation CSSNestedDeclarations CSSPositionTryRule