プッシュ 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. 新しいP-256 ECDH鍵ペアを生成します [ANSI-X9-62]。 秘密鍵を subscriptionの内部スロットに格納します。この値は決してアプリケーションから利用可能にしてはなりません。 公開鍵も内部スロットに格納され、 getKey()メソッドを PushSubscriptionに対して、引数 "p256dh"を指定して呼び出すことで取得できます。
5. 新しい認証シークレットを生成します。これは、 [RFC8291]で定義されているオクテット列です。認証シークレットを subscriptionの内部スロットに格納します。この 鍵は、getKey()メソッドを PushSubscriptionに対して、引数"auth"を指定して呼び出すことで取得できます。
6. 新しいプッシュサブスクリプションを要求します。 applicationServerKey 属性がoptionsに 設定されている場合は、その属性を含めます。発生した例外を再スローします。
7. プッシュサブスクリプションの要求が正常に完了したときは、次を実行します：
   1. subscriptionのendpoint属性を、 プッシュ サブスクリプションのプッシュエンドポイントに設定します。
   2. プッシュサブスクリプションによって提供されている場合は、subscriptionの expirationTimeを設定します。
8. subscriptionを返します。

プッシュサービスという用語は、 アプリケーションサーバーが ウェブアプリケーションにプッシュメッセージを送信できるようにする仕組みを指します。 プッシュサービスは、その配信対象となるプッシュサブスクリプションのための プッシュエンドポイントや エンドポイントを提供します。

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

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 の service worker registration が null ならば：
   1. scope に "/" および global の 対応する Document の URL を与えて basic URL parser を実行した結果を設定する。
6. それ以外の場合：
   1. アサート: this の service worker registration は service worker registration である。
   2. registration に this の service worker registration を設定する。
7. もし scope が failure または URL で scheme が "https" でないならば、 グローバルタスクをキューする （networking task source を使い、global を使って） reject promise に "NotAllowedError" の DOMException を与えて、これらの手順を終了する。
8. もし options["userVisibleOnly"] が false かつユーザーエージェントが true を必要とする場合、 グローバルタスクをキューする （networking task source を使い、global を使って） reject promise に "NotAllowedError" DOMException を与え、これらの手順を終了する。
9. もし options["applicationServerKey"] が null かつ push service が非 null を必要とする場合、 グローバルタスクをキューする（ networking task source を使い、global を使って） reject promise に "NotSupportedError" DOMException を与えて、これらの手順を終了する。
10. もし options["applicationServerKey"] が非 null ならば：
    1. もし options["applicationServerKey"] が文字列であれば、 その値を ArrayBuffer 型にし、 options["applicationServerKey"] を base64urlデコード（[RFC7515]）したオクテット列で埋める。
    2. デコードに失敗した場合は グローバルタスクをキューする （networking task source、global を使って） reject promise に "InvalidCharacterError" DOMException を与えて、これらの手順を終了する。
    3. options["applicationServerKey"] が P-256曲線上の有効な点であることを確認する。 無効な場合は グローバルタスクをキューする （networking task source、global を使って） reject promise に "InvalidAccessError" DOMException を与えて、これらの手順を終了する。
11. これらの手順を 並列で実行する：
    1. subscription を null にする。
    2. もし scope が非 null ならば：
       1. もし push subscription で、 window-accessible scope の scope が 等しい scope を持つものがあれば、subscription をその push subscription に設定する。
    3. それ以外の場合：
       1. アサート: registration は非 null である。
       2. もし registration の active worker が null ならば、 グローバルタスクをキューする （networking task source、global を使って） reject promise に "InvalidStateError" DOMException を与えて、これらの手順を終了する。
       3. もし registration の associated push subscription が非 null なら、 subscription に registration の associated push subscription を設定する。
       4. scope に registration の scope URL を設定する。
    4. permission を "push" を使う許可をリクエスト した結果にする。
    5. もし permission が "denied" であれば、 グローバルタスクをキューする （user interaction task source、global を使って） reject promise に "NotAllowedError" DOMException を与えて、これらの手順を終了する。
    6. もし subscription が非 null ならば：
       1. もし subscription にエラーがあるなら、 グローバルタスクをキューする （networking task source、global を使って） reject promise に "AbortError" DOMException を与えて、これらの手順を終了する。
       2. options 引数と subscription の options 属性を比較する。 BufferSource 値は参照ではなく内容が等しいかを比較する。
       3. もし options 内のいずれかの属性値と subscription に保存されている値が異なる場合は、 グローバルタスクをキューする （networking task source、global を使って） reject promise に "InvalidStateError" DOMException を与えて、これらの手順を終了する。
       4. グローバルタスクをキューする （networking task source、global を使って） resolve promise に subscription を与えて、これらの手順を終了する。
    7. アサート: subscription は null かつ scope は URL である。
    8. subscription に push subscription を作成 （引数は options）した結果を設定する。サブスクリプションの生成時に 例外を投げた場合は、 グローバルタスクをキューする （networking task source、global を使って） reject promise にその exception を与えて、これらの手順を終了する。
    9. subscription の scope を scope に設定する。
    10. グローバルタスクをキューする （networking task source、global を使って） resolve promise に PushSubscription （subscription に対応） を与える。
12. promise を返す。

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

1. 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がnullでない場合：
      1. プッシュサブスクリプションが存在し、 そのスコープが windowScopeである場合、subscriptionをそのプッシュサブスクリプションに設定します。
   3. それ以外の場合：
      1. 表明： registrationはnullではありません。
      2. registrationの関連付けられたプッシュサブスクリプション がnullでない場合、 subscriptionをregistrationの関連付けられた プッシュサブスクリプションに設定します。
   4. subscriptionがnullの場合、promiseをnullで解決します。
   5. subscriptionにエラーがある場合、promiseをDOMException （名前は"AbortError"）で拒否し、 これらの手順を終了します。
   6. promiseをPushSubscriptionで解決し、その値は subscriptionに対応するものとします。
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]参照）。 プッシュサービスは、 対応する秘密鍵で認証トークンが生成されていない限り、 プッシュメッセージを拒否します。

プッシュメッセージ暗号化に利用される鍵は、 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し、これらのステップを中止します。

      Note

      pushイベントは、push messageに関連付けられたキーペアを使用して正常に復号化されなかったpush subscriptionに対しては発生しません。

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が与えられた場合のnotification show stepsを実行します。

      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 を [RFC8030] に従い受信したことを認識することを意味します。

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

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

pushsubscriptionchange イベントは、 アプリケーションの制御外で プッシュ購読 が変更されたこと（例：更新、取り消し、喪失など）を示します。

"pushsubscriptionchange"イベントの発火は、 Service Worker登録 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;
};