PushMessageData — Schnittstelle · JavaScript-Referenz

Signatur

interface PushMessageData

Beschreibung

PushMessageData gehört zur Push API und steht für die Nutzdaten (den Payload), die ein Anwendungsserver über einen Push-Dienst an einen Browser schickt. Man erzeugt keine Instanz selbst, sondern bekommt sie im Service Worker über die Eigenschaft data des PushEvent, also im Handler für das Ereignis push.

Die Schnittstelle bietet mehrere Methoden, mit denen man dieselben Rohdaten in verschiedenen Formaten liest. Anders als bei Response aus der Fetch-API geben sie das Ergebnis synchron zurück, also ohne Promise:

arrayBuffer() – liefert die Daten als ArrayBuffer.
blob() – liefert die Daten als Blob.
bytes() – liefert die Daten als Uint8Array (neuere Methode).
json() – wertet die Daten als JSON aus und gibt das Ergebnis als JavaScript-Wert zurück.
text() – liefert die Daten als UTF-8-Zeichenkette.

Typischerweise verschickt der Server ein kleines JSON-Objekt mit Titel, Text und Ziel-URL. Der Service Worker liest es mit json() und zeigt dann mit registration.showNotification() eine Benachrichtigung an. Die Methoden lassen sich mehrfach aufrufen, denn anders als bei einem Response-Body werden die Daten dabei nicht verbraucht.

Rückgabewert

Typ

PushMessageData | null

Beschreibung

Die Instanz erhält man über PushEvent.data. Hat die Push-Nachricht keine Nutzdaten, ist der Wert null.

Beispiele

JSON-Nutzdaten lesen und eine Benachrichtigung anzeigen

// sw.js – Service Worker
self.addEventListener('push', (event) => {
  // data kann null sein, wenn der Server keine Nutzdaten schickt
  const payload = event.data ? event.data.json() : {};

  const title = payload.title ?? 'Neue Nachricht';
  const options = {
    body: payload.body ?? '',
    icon: '/icons/icon-192.png',
    data: { url: payload.url ?? '/' }
  };

  event.waitUntil(self.registration.showNotification(title, options));
});

Robust auswerten: erst JSON versuchen, sonst Text

// sw.js
const parsePushData = (data) => {
  if (!data) return { title: 'Update', body: '' };
  try {
    return data.json();
  } catch {
    // Kein gültiges JSON: den reinen Text als Inhalt verwenden
    return { title: 'Update', body: data.text() };
  }
};

self.addEventListener('push', (event) => {
  const { title, body } = parsePushData(event.data);
  console.log('Push empfangen:', title, body);
  event.waitUntil(self.registration.showNotification(title, { body }));
});

Push empfangen: Update Server wurde neu gestartet

Binärdaten als ArrayBuffer oder Uint8Array verarbeiten

// sw.js
self.addEventListener('push', (event) => {
  if (!event.data) return;

  const buffer = event.data.arrayBuffer();
  console.log('Größe in Bytes:', buffer.byteLength);

  // bytes() ist neuer – mit Fallback verwenden
  const bytes = typeof event.data.bytes === 'function'
    ? event.data.bytes()
    : new Uint8Array(buffer);
  console.log('Erstes Byte:', bytes[0]);

  const blob = event.data.blob();
  console.log('Blob-Größe:', blob.size);
});

Größe in Bytes: 42 Erstes Byte: 123 Blob-Größe: 42

// Wichtig · Fallstricke

Null-Prüfung: event.data ist null, wenn die Push-Nachricht keine Nutzdaten enthält. Prüfe das immer, bevor du json() oder text() aufrufst.
Synchron: Die Methoden geben kein Promise zurück. Ein await event.data.json() schadet nicht, ist aber überflüssig. Mit .then() funktioniert es dagegen nicht.
Fehler bei json(): Enthalten die Daten kein gültiges JSON, wirft json() einen SyntaxError. Fange ihn mit try/catch ab.
Verschlüsselung und Größe: Nutzdaten müssen nach RFC 8291 (Message Encryption for Web Push) verschlüsselt sein. Der Browser entschlüsselt sie automatisch. Push-Dienste begrenzen die Größe der Nutzdaten auf etwa 4 KB. Größere Daten besser per fetch() nachladen.
Sichtbare Benachrichtigung: Chrome und Safari verlangen userVisibleOnly: true. Zeigt der Service Worker nach einem Push keine Benachrichtigung an, kann der Browser eine Standardmeldung einblenden oder das Abonnement entziehen.
Kompatibilität: Die Schnittstelle gibt es nur in Service Workern und nur in sicheren Kontexten (HTTPS). Safari unterstützt Web Push ab Version 16. Unter iOS/iPadOS 16.4+ funktioniert es nur für Web-Apps, die zum Home-Bildschirm hinzugefügt wurden. bytes() kam später hinzu und fehlt in älteren Browsern.
Sicherheit: Behandle Nutzdaten als nicht vertrauenswürdig. Schreibe sie nicht ungeprüft per innerHTML in Seiten, und prüfe URLs, bevor du sie öffnest.

Siehe auch

ImageData PushManager MessagePort Metadata NDEFMessage