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

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
subscribe

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
See implementation notes.