プッシュ API

アプリケーションサーバーという用語は、ウェブアプリケーションのサーバー側コンポーネントを指します。

プッシュメッセージは、アプリケーションサーバーからウェブアプリケーションに送信されるデータです。

プッシュメッセージは、そのメッセージが送信されたアクティブワーカーに配信されます。このワーカーは、プッシュ購読に関連付けられています。サービスワーカーが現在起動していない場合は、配信のためにワーカーが起動されます。

宣言型プッシュメッセージは、プッシュメッセージの一種であり、その データはユーザーエージェントによって解釈されるJSON文書です。 ユーザーエージェントは、受信する各 プッシュメッセージを適宜解析し、そのメッセージが宣言型プッシュメッセージであるかどうかを、 宣言型プッシュメッセージパーサーを使用して判定します。

宣言型プッシュメッセージにより、サービスワーカーを関与させずに、通知を作成して 表示できます。 それでも、アプリケーションサーバーが望む場合は、サービスワーカーを 関与させることもできます。このようなシナリオでは、 たとえばストレージの逼迫によってサービスワーカーが破棄された場合に備えて、プッシュメッセージの宣言的な性質がバックアップとして 機能します。さらに、 通知データを送信するための、よりオブジェクト指向的なアプローチも提供します。

{
  "web_push": 8030,
  "notification": {
    "title": "Adaが「London」にメールを送信しました",
    "lang": "en-US",
    "dir": "ltr",
    "body": "地下鉄のストライキについて聞きましたか？",
    "navigate": "https://email.example/message/12"
  }
}

プッシュサブスクリプションとは、 ユーザー エージェントとプッシュサービスとの間で、Webアプリケーションに代わって確立されるメッセージ配信コンテキストです。

プッシュサブスクリプションには、関連付けられたスコープがあり、これはURLです。

プッシュサブスクリプションがウィンドウからアクセス可能なスコープを持つとみなされる条件は、そのスコープの パスがリストであり、そのサイズが1で、かつスコープの パス[0]が空 文字列であることです。

プッシュサブスクリプションには、関連付けられたプッシュエンドポイントがあります。これは必ず、 プッシュサービスによって公開され、アプリケーション サーバーが プッシュメッセージを送信できる絶対URLでなければなりません。プッシュエンドポイントは必ず、プッシュ サブスクリプションを一意に識別しなければなりません。

プッシュサブスクリプションには、任意で 関連付けられたサブスクリプションの有効期限 時刻を設定できます。設定されている場合、その値は必ず、1970年1月1日 00:00:00 UTCからの ミリ秒数で表される、サブスクリプションが非アクティブ化される時刻でなければなりません。ユーザーエージェントは、 可能な限り、プッシュサブスクリプションの有効期限が切れる前に更新を試みるべきです。

プッシュサブスクリプションには、関連付けられたP-256 ECDH鍵ペアと、 認証シークレットがあり、[RFC8291]に従う。

ユーザーエージェントが何らかの理由でプッシュサブスクリプションの鍵を変更する必要があり、 かつそのプッシュサブスクリプションの関連付けられたサービスワーカー登録 がnullでない場合、 ユーザーエージェントは、その更新をプッシュ サブスクリプションに対して行わなければならない。

プッシュサブスクリプションを作成するには、PushSubscriptionOptionsInit optionsDictionaryを与えて、次を行う：

1. subscriptionを、新しいPushSubscriptionとする。
2. optionsを、新たに作成したPushSubscriptionOptions オブジェクトとし、その属性を対応するメンバーおよび値で初期化する optionsDictionary。
3. subscriptionのoptions属性をoptionsに設定する。
4. subscriptionのP-256 ECDH鍵ペアを、新しいP-256 ECDH鍵ペアを生成した結果に設定する[ANSI-X9-62]。
5. subscriptionの認証シークレットを、生成した 新しい 認証シークレットの結果に設定する。これは[RFC8291]のセクション 3.2で定義されるオクテット列である。
6. 新しいプッシュサブスクリプションを要求する。 optionsのapplicationServerKey 属性が設定されている場合は、それを含める。 設定する。あらゆる例外を再スローする。
7. プッシュサブスクリプション要求が正常に完了した場合：
   1. subscriptionのendpoint属性を、 プッシュ サブスクリプションのプッシュエンドポイントに設定する。
   2. プッシュサブスクリプションによって提供されている場合、subscriptionの expirationTimeを設定する。
8. subscriptionを返す。

プッシュサービスという用語は、アプリケーション サーバーがWebアプリケーションにプッシュメッセージを送信できるようにするシステムを指す。プッシュサービスは、 それが提供するプッシュ サブスクリプションのためのプッシュエンドポイントまたはエンドポイントを提供する。

ユーザーエージェントは、プッシュ サブスクリプションの作成に使用されるプッシュサービスに接続する。ユーザーエージェントは、利用可能なプッシュサービスの選択肢を制限してもよい。 その理由には、サービスの 可用性（特定の国のファイアウォール、 または職場などのネットワークによってサービスがブロックされるかどうかを含む）、信頼性、バッテリー寿命への影響などの性能に関する懸念、および メタデータを特定のプッシュサービスへ送る、または送らないようにするための契約が含まれる。

Push APIは、強力な機能であり、 名前 "push" によって識別されます。

Permissions仕様との統合のため、 この仕様は PushPermissionDescriptor permission descriptor type を定義します。

WebIDLdictionary PushPermissionDescriptor : PermissionDescriptor {
  boolean userVisibleOnly = false;
};

userVisibleOnlyは、 userVisibleOnly と同じ意味です。

{name: "push", userVisibleOnly: false} は、 {name: "push", userVisibleOnly: true} よりも 強いです。

subscribe() メソッドの手順は以下のとおりです：

1. promiseを新しいpromiseとする。
2. globalをthisの関連する グローバルオブジェクトとする。
3. scopeをnullとする。
4. registrationをnullとする。
5. thisのサービスワーカー登録がnullの場合：
   1. scopeを、基本URLパーサーを "/"および globalの関連付けられた DocumentのURLを与えて実行した結果に設定する。
6. それ以外の場合：
   1. 表明：thisのサービスワーカー 登録はサービス ワーカー登録である。
   2. registrationをthisのサービスワーカー 登録に設定する。
7. scopeが失敗であるか、またはURLであって、そのスキームが"https"でない場合、 次に グローバル タスクをキューに入れる。ネットワーキング タスクソース上でglobalを使用して拒否する promiseを"NotAllowedError" DOMExceptionで拒否し、 これらの手順を終了する。
8. options["userVisibleOnly"] がfalseであり、ユーザー エージェントがtrueであることを要求する場合、グローバル タスクをキューに入れる。ネットワーキング タスクソース上でglobalを使用して拒否するpromiseを"NotAllowedError" DOMExceptionで拒否し、 これらの手順を終了する。
9. options["applicationServerKey"] がnullであり、 プッシュサービスがnon-nullであることを要求する場合、グローバル タスクをキューに入れる。 ネットワーキング タスクソース上でglobalを使用して拒否するpromiseを "NotSupportedError" DOMExceptionで拒否し、 これらの手順を終了する。
10. options["applicationServerKey"] がnon-nullの場合：
    1. options["applicationServerKey"] が文字列である場合、 その値を、ArrayBufferで、 次の結果として得られるオクテット列を含むものに設定する： options["applicationServerKey"] を base64urlエンコーディング[RFC7515]を使用して復号する。
    2. 復号に失敗した場合、グローバル タスクをキューに入れる。ネットワーキング タスクソース上で globalを使用して拒否するpromiseを"InvalidCharacterError" DOMException で拒否し、これらの手順を終了する。
    3. options["applicationServerKey"] が P-256曲線上の有効な点を記述していることを確認する。その値が無効である場合、グローバル タスクをキューに入れる ネットワーキング タスクソース上でglobalを使用して拒否するpromiseを "InvalidAccessError" DOMException で拒否し、これらの手順を終了する。
11. これらの手順を並行して実行する：
    1. subscriptionをnullとする。
    2. scopeがnon-nullの場合：
       1. プッシュサブスクリプションで、 ウィンドウからアクセス可能な スコープを持ち、そのスコープが 等しい scopeであるものが存在する場合、subscriptionをそのプッシュサブスクリプションに設定する。
    3. それ以外の場合：
       1. 表明： registrationはnon-nullである。
       2. registrationのアクティブ ワーカーがnullである場合、 グローバル タスクをキューに入れる。ネットワーキング タスクソース上でglobalを使用して 拒否する promiseを"InvalidStateError" DOMException で拒否し、 これらの手順を終了する。
       3. registrationの関連付けられたプッシュサブスクリプション がnon-nullである場合、 subscriptionをregistrationの関連付けられた プッシュサブスクリプションに設定する。
       4. scopeをregistrationのスコープURLに設定する。
    4. permissionを、"push"を使用する 許可を要求する結果とする。
    5. permissionが"denied"の場合、 グローバル タスクをキューに入れる。 ユーザー インタラクションタスクソース上でglobalを使用して拒否するpromiseを "NotAllowedError" DOMException で拒否し、これらの手順を終了する。
    6. subscriptionがnon-nullの場合：
       1. subscriptionにエラーがある場合、グローバル タスクをキューに入れる。 ネットワーキング タスクソース上でglobalを使用して拒否するpromiseを "AbortError" DOMException で拒否し、これらの手順を終了する。
       2. options引数をsubscriptionのoptions属性と比較する。 BufferSource 値の内容は、 参照ではなく等価性について比較される。
       3. optionsのいずれかの属性に、 subscriptionに保存されている値とは異なる値が含まれる場合、グローバル タスクをキューに入れる。ネットワーキング タスクソース上で globalを使用して拒否するpromiseを "InvalidStateError" DOMException で拒否し、これらの手順を終了する。
       4. グローバル タスクをキューに入れる。ネットワーキング タスクソース上でglobalを使用して、 解決する promiseをsubscriptionで解決し、これらの手順を終了する。
    7. 表明： subscriptionはnullであり、scopeはURLである。
    8. subscriptionを、optionsを指定してプッシュサブスクリプションを作成することを試みた結果に設定する。 サブスクリプションの作成がスローする例外場合、グローバル タスクをキューに入れる。ネットワーキング タスクソース上でglobalを使用して拒否する promiseをその例外で拒否し、これらの 手順を終了する。
    9. subscriptionのスコープをscopeに設定する。
    10. グローバル タスクをキューに入れる。ネットワーキング タスクソース上でglobalを使用して、 解決する promiseを、subscriptionに対応するPushSubscriptionで 解決する。
12. promiseを返す。

getSubscription()メソッドの手順は次のとおり：

1. promiseを新しいpromiseとする。
2. globalをthisの関連する グローバルオブジェクトとする。
3. windowScopeをnullとする。
4. registrationをnullとする。
5. thisのサービスワーカー登録がnullの場合、windowScopeを 基本URLパーサーを "/"およびglobalの 関連付けられた DocumentのURLを与えて実行した結果に設定する。
6. それ以外の場合：
   1. 表明：thisのサービスワーカー 登録はサービス ワーカー登録である。
   2. registrationをthisのサービスワーカー 登録に設定する。
7. これらの手順を並行して実行する：
   1. subscriptionをnullとする。
   2. windowScopeがnon-nullの場合：
      1. プッシュサブスクリプションで、 そのスコープが windowScopeであるものが存在する場合、subscriptionをそのプッシュサブスクリプションに設定する。
   3. それ以外の場合：
      1. 表明： registrationはnon-nullである。
      2. registrationの関連付けられたプッシュサブスクリプション がnon-nullである場合、 subscriptionをregistrationの関連付けられた プッシュサブスクリプションに設定する。
   4. subscriptionがnullの場合、promiseをnullで解決する。
   5. subscriptionにエラーがある場合、promiseをDOMExceptionで拒否する。 その名前は"AbortError"であり、 これらの手順を終了する。
   6. promiseを、subscriptionに対応するPushSubscriptionで 解決する。
8. promiseを返す。

permissionState() メソッドの手順は次の通り：

1. promise を 新しい promise にする。

2. global を this の 関連グローバルオブジェクト にする。

3. 並列で：

   1. state を "push" の 許可状態 にする。

   2. グローバルタスクをキューに入れる：networking task source 上で、global に対して promise を state で解決するためにキューする。

4. promise を返す。

プッシュサービスの利用許可は永続可能であり、有効な許可があれば以降のサブスクリプションで再確認不要です。

許可を求める必要がある場合は、subscribe() メソッドを呼び出して取得します。

WebIDL[Exposed=(Window,Worker), SecureContext]
interface PushSubscriptionOptions {
  readonly attribute boolean userVisibleOnly;
  [SameObject] readonly attribute ArrayBuffer? applicationServerKey;
};

userVisibleOnly 属性は、取得時に初期化値を返します。

applicationServerKey 属性は、取得時に初期化値を返します。

存在する場合、applicationServerKey の値は、 P-256 楕円曲線 [DSS] 上の点を含んでいる 必要があります。この点は [ANSI-X9-62] 付録Aで説明されている非圧縮形式（すなわち 0x04 オクテットで始まる 65 オクテット）でエンコードされます。 DOMString として提供される場合、その値は 必ず base64url エンコーディング [RFC7515] を用いてエンコードされている必要があります。

ユーザーエージェントは、applicationServerKey が存在しない場合に、pushサービス が運用上必要とする場合、サブスクリプションの試行を拒否する 場合があります。

applicationServerKey の値は、 メッセージ暗号化 [RFC8291] に使用される値とは 異なるものでなければなりません。

WebIDLdictionary PushSubscriptionOptionsInit {
  boolean userVisibleOnly = false;
  (BufferSource or DOMString)? applicationServerKey = null;
};

userVisibleOnlyメンバーは、 trueに設定されると、プッシュ サブスクリプションが、たとえばWeb通知を表示することによって、その効果がユーザーに見えるようにされるプッシュメッセージにのみ使用されることを示す。 [NOTIFICATIONS]

PushSubscriptionOptionsInitは、 プッシュサブスクリプションに関連付けられた追加のオプションを表す。ユーザーエージェントは、 ユーザーから明示的な許可を要求するときに、これらのオプションを考慮してもよい。 オプションが考慮される場合、 ユーザー エージェントは、受信するプッシュメッセージに対してそれを強制するべきである。

これらのオプションは任意であり、ユーザーエージェントは、その サブセットのみをサポートすることを選択してもよい。ユーザーエージェントは、サポートしていないオプションを公開してはならない。

一度設定されると、プッシュサブスクリプションのオプションは変更できない。既存のプッシュ サブスクリプションは、unsubscribeを介して購読解除し、新しいオプションを持つ プッシュサブスクリプションを作成できる。

applicationServerKeyメンバーは、ユーザー エージェントが プッシュサービスとのプッシュサブスクリプションを確立するときに使用される。 applicationServerKey オプションには、アプリケーションサーバーの楕円曲線公開 鍵が含まれる。これは、アプリケーションサーバーが [RFC8292]で定義されているように、このプッシュ サブスクリプションにプッシュメッセージを送信するとき、自身を認証するために使用する鍵であり、 プッシュサービスは、対応する秘密鍵が 認証トークンの生成に使用されない限り、あらゆる プッシュメッセージを拒否する。

プッシュメッセージの暗号化に使用される暗号化鍵は、Webアプリケーションに getKey()メソッドまたは PushSubscriptionのシリアライザーを通じて提供される。各鍵には、 PushEncryptionKeyName 列挙型の値を使用して名前が付けられる。

WebIDLenum PushEncryptionKeyName {
  "p256dh",
  "auth"
};

p256dh 値は [RFC8291]で記述されるP-256 ECDH ディフィー・ヘルマン公開鍵の取得に使います。

auth 値は [RFC8291]で記述される認証用シークレットの取得に使います。

Service Worker仕様は、ServiceWorkerGlobalScope インターフェースを定義しています [SERVICE-WORKERS]。この仕様はこれを拡張します。

WebIDL[Exposed=ServiceWorker, SecureContext]
partial interface ServiceWorkerGlobalScope {
  attribute EventHandler onpush;
  attribute EventHandler onpushsubscriptionchange;
};

onpush 属性は イベントハンドラIDL属性であり、 対応する イベントハンドライベントタイプは "push" です。 "push" イベントは プッシュメッセージが プッシュ購読に対して受信されたことを示します。

onpushsubscriptionchange 属性は イベントハンドラIDL属性であり、 対応する イベントハンドライベントタイプは "pushsubscriptionchange" です。

WebIDL[Exposed=ServiceWorker, SecureContext]
interface PushEvent : ExtendableEvent {
  constructor(DOMString type, optional PushEventInit eventInitDict = {});
  readonly attribute PushMessageData? data;
  readonly attribute Notification? notification;
};

dictionary PushEventInit : ExtendableEventInit {
  PushMessageDataInit? data = null;
  Notification? notification = null;
};

typedef (BufferSource or USVString) PushMessageDataInit;

constructor の PushEvent インターフェース、または PushEvent インターフェースを継承するインターフェースが呼び出されたとき、通常の イベント構築手順に加えて以下の手順を実行します：

1. eventInitDict の data メンバーが存在しない場合、イベントの data 属性を null に設定し、この手順を終了します。
2. b を バイト列を抽出するによって eventInitDict の "data" メンバーから得た結果とします。
3. イベントの data 属性に、PushMessageData インスタンス（bytes が b）を設定します。

data 属性は初期化時の値を返します。

notification 属性は初期化時の値を返します。

user agentがpush serviceからpush messageを受信すると、 それはMUST次のステップを実行します。

1. subscriptionを、push messageに対応するアクティブなpush subscriptionとします。

2. registrationをsubscriptionのassociated service worker registrationとします。

3. bytesをnullとします。

4. もしpush messageがペイロードを含む場合：

   1. subscriptionに関連付けられたキーペアからの秘密鍵と[RFC8291]で説明されているプロセスを使用して、push messageのペイロードを復号化します。bytesを結果のbyte sequenceに設定します。

   2. もし、何らかの理由でpush messageのペイロードを復号化できなかった場合、acknowledge push messageし、これらのステップを中止します。

      注記

      pushイベントは、プッシュ メッセージが正常に プッシュサブスクリプションに関連付けられた鍵ペアを使用して復号されなかった場合、発火されない。

5. もしbytesがnullでない場合：

   1. baseURLをsubscriptionのscopeとします。

   2. originをbaseURLのoriginとします。

   3. fallbackTimestampをcurrent coarsened wall timeとします。

   4. declarativeResultを、bytes、origin、 baseURL、およびfallbackTimestampが与えられた場合のdeclarative push message parserを実行した結果とします。

   5. もしdeclarativeResultがfailureでない場合：

      1. notificationをdeclarativeResultのnotificationとします。

      2. notificationのservice worker registrationをregistrationに設定します。

      3. notificationShownをfalseとします。

      4. もしdeclarativeResultのmutable がtrueで、registrationがnullでない場合：

         1. resultを、registration、null、およびnotificationを表す新しいNotification オブジェクトが与えられた場合のfiring a push eventの結果とします。

         2. もしresultがfailureでない場合、notificationShownをresultのnotification shownに設定します。

      5. notificationShownがfalseの場合、通知 表示手順を notificationとnullを与えて実行する。

         注記

         環境 設定オブジェクトがないため、nullが渡される。これにより、 notificationのアイコンなどのリソースが、 サービス ワーカーを介さずに取得されることも保証される。

      6. Acknowledge push messageし、これらのステップを中止します。

6. もしregistrationがnullの場合、これらのステップを中止します。

7. dataを、PushMessageDataオブジェクトとします。このオブジェクトのbytesは、もしbytesがnullでない場合はbytes、それ以外の場合はnullです。

8. resultを、registration、data、およびnullが与えられた場合のfiring a push eventの結果とします。

9. もしresultがfailureで、同じpush messageがservice worker registrationに複数回配信されたにもかかわらず成功しなかった場合、acknowledge push messageします。

10. もしresultがfailureでない場合、acknowledge push messageします。

pushイベント結果は、 タプルであり、 notification shown（boolean）を含みます。

pushイベントの発火は、 Service Worker登録 registration、 PushMessageData オブジェクトまたは null data、 notification または null notification を受け取り、以下の手順を実行します。失敗または pushイベント結果を返します。

1. notificationResult を null で初期化します。

2. registration の showNotification()が正常に呼び出されたか を false に設定します。

3. 機能的イベントの発火で "push" を PushEvent 型で registration に対して以下のプロパティで発火する：

   data

   data

   notification

   notification

   その後 dispatchedEvent を使って以下の手順を並列で実行：

   1. extend lifetime promises のすべてのpromiseが解決されるまで待機する。

   2. 正常に解決されなければ notificationResult を失敗に設定する。

   3. そうでなければ notificationResult を registration の showNotification()が正常に呼び出されたか の値に設定する。

4. notificationResult が null でなくなるまで待機する。

5. notificationResult が失敗なら失敗を返す。

6. Assert: notificationResult は boolean である。

7. (notificationResult) を返す。

プッシュメッセージを確認応答するとは、プッシュメッセージ pushMessageを与えられたとき、pushMessageの受信を [RFC8030]に従って確認応答することを意味する。

プッシュメッセージを確認応答すると、プッシュサービスは メッセージの配信を停止し、アプリケーションサーバーに成功を報告する。これにより、 同じ プッシュメッセージがプッシュサービスによって無期限に再試行されることを防ぐ。

確認応答することは、アプリケーションサーバーが誤って プッシュメッセージの配信成功を示す 配信確認を受信する可能性があることも意味する。したがって、 確認応答する前に複数回の拒否を許可するべきであり、少なくとも 3回の試行を許可することが推奨される。

pushsubscriptionchangeイベントは、 プッシュサブスクリプションの変更を示す。 これは、たとえば更新、取り消し、または喪失されたために、アプリケーションの制御外で 引き起こされたものである。

「pushsubscriptionchange」イベントを発火するには、サービスワーカー 登録であるregistration、newSubscription、および oldSubscriptionが与えられたとき、ユーザー エージェントは、機能イベントを発火しなければならない。 名前は「pushsubscriptionchange」とし、 PushSubscriptionChangeEventを registration上で次のプロパティとともに使用する：

newSubscription

newSubscription

oldSubscription

oldSubscription

WebIDL[Exposed=ServiceWorker, SecureContext]
interface PushSubscriptionChangeEvent : ExtendableEvent {
  constructor(DOMString type, optional PushSubscriptionChangeEventInit eventInitDict = {});
  readonly attribute PushSubscription? newSubscription;
  readonly attribute PushSubscription? oldSubscription;
};

WebIDLdictionary PushSubscriptionChangeEventInit : ExtendableEventInit {
  PushSubscription newSubscription = null;
  PushSubscription oldSubscription = null;
};