PushManager: subscribe()-Methode

Baseline 2023

Newly available

Since March 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.

Hinweis: Diese Funktion ist in Web Workers verfügbar.

Die subscribe()-Methode der PushManager-Schnittstelle abonniert einen Push-Dienst.

Sie gibt ein Promise zurück, das zu einem PushSubscription-Objekt auflöst, das Details eines Push-Abonnements enthält. Ein neues Push-Abonnement wird erstellt, wenn der aktuelle Service-Worker kein bestehendes Abonnement hat.

Syntax

js
subscribe(options)

Parameter

options Optional

Ein Objekt, das optionale Konfigurationsparameter enthält. Es kann die folgenden Eigenschaften haben:

userVisibleOnly

Ein Boolean, der angibt, dass das zurückgegebene Push-Abonnement nur für Nachrichten verwendet wird, deren Wirkung dem Benutzer sichtbar gemacht wird.

applicationServerKey

Ein Base64-kodierter String oder ArrayBuffer, der einen ECDSA-P-256-öffentlichen Schlüssel enthält, den der Push-Server zur Authentifizierung Ihres Anwendungsservers verwendet. Wenn angegeben, müssen alle Nachrichten von Ihrem Anwendungsserver das VAPID-Authentifizierungsschema verwenden und ein JWT enthalten, das mit dem entsprechenden privaten Schlüssel signiert ist. Dieser Schlüssel IST NICHT derselbe ECDH-Schlüssel, den Sie zur Verschlüsselung der Daten verwenden. Weitere Informationen finden Sie im Artikel "Using VAPID with WebPush" (englisch).

Hinweis: Dieser Parameter ist in einigen Browsern wie Chrome und Edge erforderlich. Diese werden das Promise ablehnen, wenn userVisibleOnly nicht auf true gesetzt ist.

Rückgabewert

Ein Promise, das zu einem PushSubscription-Objekt auflöst.

Beispiele

js
this.onpush = (event) => {
  console.log(event.data);
  // From here we can write the data to IndexedDB, send it to any open
  // windows, display a notification, etc.
};

navigator.serviceWorker.register("serviceworker.js");

// Use serviceWorker.ready to ensure that you can subscribe for push
navigator.serviceWorker.ready.then((serviceWorkerRegistration) => {
  const options = {
    userVisibleOnly: true,
    applicationServerKey,
  };
  serviceWorkerRegistration.pushManager.subscribe(options).then(
    (pushSubscription) => {
      console.log(pushSubscription.endpoint);
      // The push subscription details needed by the application
      // server are now available, and can be sent to it using,
      // for example, the fetch() API.
    },
    (error) => {
      // During development it often helps to log errors to the
      // console. In a production environment it might make sense to
      // also report information about errors back to the
      // application server.
      console.error(error);
    },
  );
});

Reaktion auf Benutzeraktionen

subscribe()-Aufrufe sollten als Reaktion auf eine Benutzeraktion, wie zum Beispiel das Klicken eines Buttons, erfolgen:

js
btn.addEventListener("click", () => {
  serviceWorkerRegistration.pushManager
    .subscribe(options)
    .then((pushSubscription) => {
      // handle subscription
    });
});

Dies ist nicht nur eine bewährte Methode – Sie sollten Benutzer nicht mit Benachrichtigungen belästigen, denen sie nicht zugestimmt haben – sondern zukünftig werden Browser ausdrücklich Benachrichtigungen verbieten, die nicht als Reaktion auf eine Benutzeraktion ausgelöst werden. Firefox tut dies bereits ab Version 72, zum Beispiel.

Spezifikationen

Specification
Push API
# dom-pushmanager-subscribe

Browser-Kompatibilität

BCD tables only load in the browser