Nutzer für Push-Benachrichtigungen abonnieren

Wenn Sie Push-Nachrichten senden möchten, müssen Sie zuerst die Berechtigung des Nutzers einholen und dann sein Gerät für einen Push-Dienst registrieren. Dazu müssen Sie mit der JavaScript API ein PushSubscription-Objekt abrufen, das Sie dann an Ihren Server senden.

Die JavaScript API vereinfacht diesen Prozess. In diesem Leitfaden wird der gesamte Ablauf beschrieben, einschließlich der Erkennung von Funktionen, der Anforderung von Berechtigungen und der Verwaltung des Aboprozesses.

Funktionserkennung

Prüfen Sie zuerst, ob der Browser Push-Benachrichtigungen unterstützt. Sie können die Push-Unterstützung mit zwei Prüfungen testen:

• Suchen Sie im Objekt navigator nach serviceWorker.
• Suchen Sie im Objekt window nach PushManager.

if (!('serviceWorker' in navigator)) {
  // Service Worker isn't supported on this browser, disable or hide UI.
  return;
}

if (!('PushManager' in window)) {
  // Push isn't supported on this browser, disable or hide UI.
  return;
}

Die Browserunterstützung für Service Worker und Push-Benachrichtigungen nimmt zwar zu, Sie sollten aber immer beide Funktionen erkennen und Ihre Anwendung schrittweise verbessern.

Service Worker registrieren

Nach der Funktionserkennung wissen Sie, dass Service Worker und Push-Benachrichtigungen unterstützt werden. Registrieren Sie als Nächstes Ihren Service Worker.

Wenn Sie einen Service Worker registrieren, teilen Sie dem Browser den Speicherort Ihrer Service Worker-Datei mit. Die Datei ist eine JavaScript-Datei, aber der Browser gewährt ihr Zugriff auf Service Worker-APIs, einschließlich Push-Messaging. Der Browser führt die Datei in einer Service Worker-Umgebung aus.

Rufen Sie navigator.serviceWorker.register() auf und übergeben Sie den Pfad zu Ihrer Datei, um einen Service Worker zu registrieren. Beispiel:

function registerServiceWorker() {
  return navigator.serviceWorker
    .register('/service-worker.js')
    .then(function (registration) {
      console.log('Service worker successfully registered.');
      return registration;
    })
    .catch(function (err) {
      console.error('Unable to register service worker.', err);
    });
}

Mit dieser Funktion wird dem Browser der Speicherort Ihrer Service Worker-Datei mitgeteilt. Hier befindet sich die Service Worker-Datei unter /service-worker.js. Nachdem Sie register() aufgerufen haben, führt der Browser die folgenden Schritte aus:

1. Laden Sie die Service Worker-Datei herunter.

2. Führen Sie das JavaScript aus.

3. Wenn die Datei ohne Fehler ausgeführt wird, wird das von register() zurückgegebene Promise aufgelöst. Wenn Fehler auftreten, wird das Promise abgelehnt.

Hinweis: Wenn register() abgelehnt wird, prüfen Sie in den Chrome-Entwicklertools, ob Ihr JavaScript Tippfehler oder Fehler enthält.

Wenn register() aufgelöst wird, wird ein ServiceWorkerRegistration zurückgegeben. Mit dieser Registrierung greifen Sie auf die PushManager API zu.

Browserkompatibilität der PushManager API

Berechtigung anfordern

Nachdem Sie Ihren Service Worker registriert und die Berechtigung erhalten haben, müssen Sie die Berechtigung des Nutzers zum Senden von Push-Nachrichten einholen.

Die API zum Einholen der Berechtigung ist einfach. Die API wurde jedoch vor Kurzem geändert. Anstelle eines Rückrufs wird jetzt ein Promise zurückgegeben. Da Sie nicht feststellen können, welche API-Version der Browser implementiert, müssen Sie beide Versionen implementieren und verarbeiten.

function askPermission() {
  return new Promise(function (resolve, reject) {
    const permissionResult = Notification.requestPermission(function (result) {
      resolve(result);
    });

    if (permissionResult) {
      permissionResult.then(resolve, reject);
    }
  }).then(function (permissionResult) {
    if (permissionResult !== 'granted') {
      throw new Error("We weren't granted permission.");
    }
  });
}

Im vorherigen Code wird durch den Aufruf von Notification.requestPermission() eine Aufforderung für den Nutzer angezeigt:

Nachdem der Nutzer auf die Berechtigungsaufforderung reagiert hat, indem er Zulassen oder Blockieren ausgewählt oder die Aufforderung geschlossen hat, erhalten Sie das Ergebnis als String: 'granted', 'default' oder 'denied'.

Im Beispielcode wird das von askPermission() zurückgegebene Promise aufgelöst, wenn die Berechtigung erteilt wird. Andernfalls wird ein Fehler ausgegeben und das Promise wird abgelehnt.

Behandeln Sie den Grenzfall, in dem der Nutzer auf die Schaltfläche Blockieren klickt. In diesem Fall kann Ihre Web-App den Nutzer nicht noch einmal um die Berechtigung bitten. Der Nutzer muss Ihre App manuell entsperren, indem er den Berechtigungsstatus in einem Einstellungsfeld ändert. Überlegen Sie sich genau, wann und wie Sie um die Berechtigung bitten, denn wenn ein Nutzer auf Blockieren klickt, ist es nicht einfach, diese Entscheidung rückgängig zu machen.

Die meisten Nutzer erteilen die Berechtigung, wenn sie verstehen, warum die App sie anfordert.

In diesem Dokument wird beschrieben, wie einige beliebte Websites später um Berechtigungen bitten.

Nutzer mit PushManager abonnieren

Nachdem Sie Ihren Service Worker registriert und die Berechtigung erhalten haben, können Sie einen Nutzer abonnieren, indem Sie registration.pushManager.subscribe() aufrufen.

function subscribeUserToPush() {
  return navigator.serviceWorker
    .register('/service-worker.js')
    .then(function (registration) {
      const subscribeOptions = {
        userVisibleOnly: true,
        applicationServerKey: urlBase64ToUint8Array(
          'BEl62iUYgUivxIkv69yViEuiBIa-Ib9-SkvMeAtA3LFgDzkrxZJjSgSnfckjBJuBkr3qBUYIHBQFLXYp5Nksh8U',
        ),
      };

      return registration.pushManager.subscribe(subscribeOptions);
    })
    .then(function (pushSubscription) {
      console.log(
        'Received PushSubscription: ',
        JSON.stringify(pushSubscription),
      );
      return pushSubscription;
    });
}

Wenn Sie die Methode subscribe() aufrufen, übergeben Sie ein options-Objekt, das aus erforderlichen und optionalen Parametern besteht.

In diesem Abschnitt werden die Optionen beschrieben, die Sie übergeben können.

userVisibleOnly-Optionen

Als Push-Messaging in Browsern eingeführt wurde, waren sich Entwickler unsicher, ob sie Push-Nachrichten senden sollten, ohne eine Benachrichtigung anzuzeigen. Dies wird häufig als „Silent Push“ bezeichnet, da der Nutzer nicht weiß, dass im Hintergrund ein Ereignis aufgetreten ist.

Die Befürchtung war, dass Entwickler den Standort eines Nutzers ohne dessen Wissen kontinuierlich verfolgen könnten.

Um dieses Szenario zu vermeiden und Spezifikationsautoren die Möglichkeit zu geben, zu überlegen, wie diese Funktion am besten unterstützt werden kann, wurde die Option userVisibleOnly hinzugefügt. Wenn Sie den Wert true übergeben, stimmen Sie symbolisch mit dem Browser überein, dass die Web-App jedes Mal eine Benachrichtigung anzeigt, wenn sie eine Push-Nachricht empfängt (d. h. kein Silent Push).

Sie müssen den Wert true übergeben. Wenn Sie den Schlüssel userVisibleOnly nicht angeben oder false übergeben, wird der folgende Fehler angezeigt:

Chrome currently only supports the Push API for subscriptions that will result
in user-visible messages. You can indicate this by calling
`pushManager.subscribe({userVisibleOnly: true})` instead. See
[https://goo.gl/yqv4Q4](https://goo.gl/yqv4Q4) for more details.

Chrome unterstützt die Push API nur für Abonnements, die zu für Nutzer sichtbaren Nachrichten führen. Geben Sie dies an, indem Sie pushManager.subscribe({userVisibleOnly: true}) aufrufen. Weitere Informationen finden Sie unter https://goo.gl/yqv4Q4.

Anscheinend wird der globale Silent Push in Chrome nicht implementiert. Stattdessen wird eine Budget-API in Betracht gezogen, mit der Web-Apps je nach Nutzung eine bestimmte Anzahl von Silent-Push-Nachrichten senden können.

Option „applicationServerKey“

In diesem Dokument wurden zuvor Anwendungsserver-Schlüssel erwähnt. Ein Push-Dienst verwendet Anwendungsserver-Schlüssel, um die Anwendung zu identifizieren, die einen Nutzer abonniert, und dafür zu sorgen, dass derselben Anwendung Nachrichten an diesen Nutzer gesendet werden.

Anwendungsserver-Schlüssel sind ein öffentliches und ein privates Schlüsselpaar, das für Ihre Anwendung eindeutig ist. Halten Sie den privaten Schlüssel für Ihre Anwendung geheim und geben Sie den öffentlichen Schlüssel frei weiter.

Die Option applicationServerKey, die an den subscribe()-Aufruf übergeben wird, ist der öffentliche Schlüssel Ihrer Anwendung. Der Browser übergibt diesen Schlüssel an einen Push-Dienst, wenn der Nutzer abonniert wird. So kann der Push-Dienst den öffentlichen Schlüssel Ihrer Anwendung mit der PushSubscription des Nutzers verknüpfen.

Das folgende Diagramm veranschaulicht diese Schritte.

1. Laden Sie Ihre Web-App in einem Browser und rufen Sie subscribe() auf. Übergeben Sie dabei Ihren öffentlichen Anwendungsserver-Schlüssel.
2. Der Browser sendet dann eine Netzwerkanfrage an einen Push-Dienst, der einen Endpunkt generiert, diesen Endpunkt mit dem öffentlichen Schlüssel Ihrer Anwendung verknüpft und den Endpunkt an den Browser zurückgibt.
3. Der Browser fügt diesen Endpunkt dem PushSubscription hinzu, das vom subscribe()-Promise zurückgegeben wird.

Wenn Sie eine Push-Nachricht senden, erstellen Sie einen Authorization-Header, der mit dem privaten Schlüssel Ihres Anwendungsservers signierte Informationen enthält. Wenn der Push-Dienst eine Anfrage zum Senden einer Push-Benachrichtigung empfängt, wird der signierte Authorization-Header validiert, indem der öffentliche Schlüssel nachgeschlagen wird, der mit dem Endpunkt verknüpft ist, der die Anfrage empfängt. Wenn die Signatur gültig ist, weiß der Push-Dienst, dass die Anfrage vom Anwendungsserver mit dem entsprechenden privaten Schlüssel stammt. Diese Sicherheitsmaßnahme soll verhindern, dass andere Nachrichten an die Nutzer Ihrer Anwendung senden.

Technisch gesehen ist applicationServerKey optional. Für die einfachste Implementierung in Chrome ist sie jedoch erforderlich und andere Browser benötigen sie möglicherweise in Zukunft. In Firefox ist das optional.

Der Anwendungsserver-Schlüssel wird in der VAPID-Spezifikation definiert. Wenn Sie Verweise auf Anwendungsserver- oder VAPID-Schlüssel sehen, denken Sie daran, dass es sich um dasselbe handelt.

Anwendungsserverschlüssel erstellen

Sie können ein öffentliches und ein privates Set von Anwendungsserver-Schlüsseln erstellen, indem Sie web-push-codelab.glitch.me aufrufen oder die Web-Push-Befehlszeile verwenden, um Schlüssel wie folgt zu generieren:

    $ npm install -g web-push
    $ web-push generate-vapid-keys

Erstellen Sie diese Schlüssel nur einmal für Ihre Anwendung und sorgen Sie dafür, dass der private Schlüssel privat bleibt.

Berechtigungen und subscribe()

Der Aufruf von subscribe() hat eine Nebenwirkung. Wenn Ihre Web-App nicht berechtigt ist, Benachrichtigungen anzuzeigen, wenn Sie subscribe() aufrufen, fordert der Browser die Berechtigungen für Sie an. Das ist nützlich, wenn Ihre Benutzeroberfläche mit diesem Ablauf funktioniert. Wenn Sie jedoch mehr Kontrolle haben möchten (was die meisten Entwickler wünschen), verwenden Sie die Notification.requestPermission() API, die in diesem Dokument bereits beschrieben wurde.

PushSubscription-Übersicht

Sie rufen subscribe() auf, übergeben Optionen und erhalten ein Promise, das zu einem PushSubscription aufgelöst wird. Beispiel:

function subscribeUserToPush() {
  return navigator.serviceWorker
    .register('/service-worker.js')
    .then(function (registration) {
      const subscribeOptions = {
        userVisibleOnly: true,
        applicationServerKey: urlBase64ToUint8Array(
          'BEl62iUYgUivxIkv69yViEuiBIa-Ib9-SkvMeAtA3LFgDzkrxZJjSgSnfckjBJuBkr3qBUYIHBQFLXYp5Nksh8U',
        ),
      };

      return registration.pushManager.subscribe(subscribeOptions);
    })
    .then(function (pushSubscription) {
      console.log(
        'Received PushSubscription: ',
        JSON.stringify(pushSubscription),
      );
      return pushSubscription;
    });
}

Das PushSubscription-Objekt enthält alle Informationen, die zum Senden von Push-Benachrichtigungen an diesen Nutzer erforderlich sind. Wenn Sie den Inhalt mit JSON.stringify() ausgeben, sehen Sie Folgendes:

    {
      "endpoint": "https://some.pushservice.com/something-unique",
      "keys": {
        "p256dh":
    "BIPUL12DLfytvTajnryr2PRdAgXS3HGKiLqndGcJGabyhHheJYlNGCeXl1dn18gSJ1WAkAPIxr4gK0_dQds4yiI=",
        "auth":"FPssNDTKnInHVndSTdbKFw=="
      }
    }

endpoint ist die URL des Push-Dienstes. Wenn Sie eine Push-Nachricht auslösen möchten, senden Sie eine POST-Anfrage an diese URL.

Das keys-Objekt enthält die Werte, die zum Verschlüsseln von Nachrichtendaten verwendet werden, die mit einer Push-Nachricht gesendet werden. (Die Nachrichtenverschlüsselung wird später in diesem Dokument behandelt.)

Abo an Ihren Server senden

Nachdem Sie ein Push-Abo haben, senden Sie es an Ihren Server. Sie legen fest, wie die Daten gesendet werden. Ein Tipp ist, JSON.stringify() zu verwenden, um alle erforderlichen Daten aus dem Abo-Objekt zu extrahieren. Alternativ können Sie das Ergebnis auch manuell zusammenstellen, z. B. so:

const subscriptionObject = {
  endpoint: pushSubscription.endpoint,
  keys: {
    p256dh: pushSubscription.getKeys('p256dh'),
    auth: pushSubscription.getKeys('auth'),
  },
};

// The above is the same output as:

const subscriptionObjectToo = JSON.stringify(pushSubscription);

Verwenden Sie Folgendes, um das Abo über die Webseite zu senden:

function sendSubscriptionToBackEnd(subscription) {
  return fetch('/api/save-subscription/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(subscription),
  })
    .then(function (response) {
      if (!response.ok) {
        throw new Error('Bad status code from server.');
      }

      return response.json();
    })
    .then(function (responseData) {
      if (!(responseData.data && responseData.data.success)) {
        throw new Error('Bad response from server.');
      }
    });
}

Der Node.js-Server empfängt diese Anfrage und speichert die Daten zur späteren Verwendung in einer Datenbank.

app.post('/api/save-subscription/', function (req, res) {
  if (!isValidSaveRequest(req, res)) {
    return;
  }

  return saveSubscriptionToDatabase(req.body)
    .then(function (subscriptionId) {
      res.setHeader('Content-Type', 'application/json');
      res.send(JSON.stringify({data: {success: true}}));
    })
    .catch(function (err) {
      res.status(500);
      res.setHeader('Content-Type', 'application/json');
      res.send(
        JSON.stringify({
          error: {
            id: 'unable-to-save-subscription',
            message:
              'The subscription was received but we were unable to save it to our database.',
          },
        }),
      );
    });
});

Mit den PushSubscription-Details auf Ihrem Server können Sie Ihrem Nutzer jederzeit eine Nachricht senden.

Abo regelmäßig verlängern, um ein Ablaufen zu verhindern

Wenn Sie Push-Benachrichtigungen abonnieren, erhalten Sie oft eine PushSubscription.expirationTime von null. Theoretisch bedeutet das, dass das Abo nie abläuft. Im Gegensatz dazu gibt DOMHighResTimeStamp die genaue Ablaufzeit an. In der Praxis lassen Browser Abos jedoch häufig auslaufen. Das kann beispielsweise passieren, wenn über einen längeren Zeitraum keine Push-Benachrichtigungen empfangen werden oder wenn der Browser erkennt, dass der Nutzer keine App verwendet, die die Berechtigung für Push-Benachrichtigungen hat. Eine Möglichkeit, dies zu verhindern, besteht darin, den Nutzer bei jeder empfangenen Benachrichtigung neu zu abonnieren, wie im folgenden Snippet gezeigt. Dazu müssen Sie Benachrichtigungen häufig genug senden, damit der Browser das Abo nicht automatisch ablaufen lässt. Sie sollten die Vor- und Nachteile von berechtigten Benachrichtigungen sorgfältig abwägen und den Nutzer nicht nur deshalb mit Benachrichtigungen überschütten, um das Ablaufen des Abos zu verhindern. Letztendlich sollten Sie nicht versuchen, die Bemühungen des Browsers zu umgehen, Nutzer vor lange vergessenen Benachrichtigungsabos zu schützen.

/* In the Service Worker. */

self.addEventListener('push', function(event) {
  console.log('Received a push message', event);

  // Display notification or handle data
  // Example: show a notification
  const title = 'New Notification';
  const body = 'You have new updates!';
  const icon = '/images/icon.png';
  const tag = 'simple-push-demo-notification-tag';

  event.waitUntil(
    self.registration.showNotification(title, {
      body: body,
      icon: icon,
      tag: tag
    })
  );

  // Attempt to resubscribe after receiving a notification
  event.waitUntil(resubscribeToPush());
});

function resubscribeToPush() {
  return self.registration.pushManager.getSubscription()
    .then(function(subscription) {
      if (subscription) {
        return subscription.unsubscribe();
      }
    })
    .then(function() {
      return self.registration.pushManager.subscribe({
        userVisibleOnly: true,
        applicationServerKey: urlBase64ToUint8Array('YOUR_PUBLIC_VAPID_KEY_HERE')
      });
    })
    .then(function(subscription) {
      console.log('Resubscribed to push notifications:', subscription);
      // Optionally, send new subscription details to your server
    })
    .catch(function(error) {
      console.error('Failed to resubscribe:', error);
    });
}

Häufig gestellte Fragen

Hier sind einige häufig gestellte Fragen:

Kann ich den Push-Dienst ändern, den ein Browser verwendet?

Nein, der Browser wählt den Push-Dienst aus. Wie in diesem Dokument im Zusammenhang mit dem subscribe()-Aufruf beschrieben, sendet der Browser Netzwerkanfragen an den Push-Dienst, um die Details abzurufen, aus denen sich die PushSubscription zusammensetzt.

Verwenden verschiedene Push-Dienste unterschiedliche APIs?

Alle Push-Dienste erwarten dieselbe API.

Diese gemeinsame API, das Web Push Protocol, beschreibt die Netzwerkanfrage, die Ihre Anwendung zum Auslösen einer Push-Benachrichtigung sendet.

Wenn ich einen Nutzer auf meinem Computer abonniere, bin ich dann auch auf meinem Smartphone abonniert?

Nein. Ein Nutzer muss sich in jedem Browser, in dem er Nachrichten empfangen möchte, für Push-Benachrichtigungen registrieren. Dazu muss der Nutzer die Berechtigung auf jedem Gerät erteilen.

Nächste Schritte

• Web-Push-Benachrichtigungen – Übersicht
• Funktionsweise von Push-Benachrichtigungen
• Nutzer abonnieren
• Nutzerfreundlichkeit von Berechtigungen
• Nachrichten mit Web-Push-Bibliotheken senden
• Web-Push-Protokoll
• Push-Ereignisse verarbeiten
• Benachrichtigung anzeigen
• Benachrichtigungsverhalten
• Häufige Benachrichtigungsmuster
• Häufig gestellte Fragen zu Push-Benachrichtigungen
• Häufige Probleme und Melden von Fehlern

Codelabs

• Push-Benachrichtigungsclient erstellen
• Push-Benachrichtigungsserver erstellen