PushManager: subscribe() メソッド

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.

subscribe() は PushManager インターフェイスのメソッドで、プッシュサービスに加入します。

これは、プッシュサブスクリプションの詳細を含む PushSubscription オブジェクトで解決される Promise を返します。現在のサービスワーカーに既存のサブスクリプションがない場合、新しいプッシュサブスクリプションが生成されます。

構文

js
subscribe(options)

引数

options 省略可

オプションの設定パラメーターを含むオブジェクトです。以下のプロパティを指定することができます。

userVisibleOnly

論理値で、返されたプッシュサブスクリプションの効果が、ユーザーに表示するメッセージにのみ使われるかを示します。

applicationServerKey

Base64 でエンコードされた文字列または ArrayBuffer で、プッシュサーバーがアプリケーションサーバーを認証するために使用する楕円曲線 DSA P-256 公開鍵が入ります。指定した場合は、アプリケーションサーバーから発するすべてのメッセージで VAPID 認証スキームを使用しなければならず、また対応する秘密鍵で署名した JWT を含めなければなりません。この鍵は、データを暗号化するために使用する ECDH 鍵と同じではありません。詳しくは "Using VAPID with WebPush" をご覧ください。

メモ: この引数は Chrome や Edge など、一部のブラウザーでは必須です。

返値

Promise です。これは PushSubscription オブジェクトで解決します。

例

js
this.onpush = (event) => {
  console.log(event.data);
  // ここから、IndexedDB にデータを書き込んだり、いずれかのウィンドウに
  // それを送信したり、通知を表示したりできます。
};

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

// serviceWorker.ready を使用して、プッシュの購読ができることを確かめます。
navigator.serviceWorker.ready.then((serviceWorkerRegistration) => {
  const options = {
    userVisibleOnly: true,
    applicationServerKey,
  };
  serviceWorkerRegistration.pushManager.subscribe(options).then(
    (pushSubscription) => {
      console.log(pushSubscription.endpoint);
      // アプリケーションサーバーが必要としているプッシュサブスクリプションの
      // 詳細はここから使用できます。たとえば、XMLHttpRequest を使用して
      // これを送信できます。
    },
    (error) => {
      // 開発中は、コンソールにエラーを表示するのに役立ちます。
      // 本番環境では、アプリケーションサーバーにエラー情報を送信
      // するためにも 役立ちます。
      console.error(error);
    },
  );
});

ユーザーのジェスチャーへの反応

subscribe() の呼び出しは、例えばボタンをクリックするようなユーザーのジェスチャーに反応して行うべきです。

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

これは最善の手法であるだけでなく、ユーザーが同意していない通知を送りつけるべきではありません。今後、ブラウザーはユーザーのジェスチャーに応答して発生していない通知を明示的に許可しないようになります。例えば、Firefox はバージョン 72 から既にこの例を行っています。

仕様書

Specification
Push API
# dom-pushmanager-subscribe

ブラウザーの互換性

BCD tables only load in the browser