プッシュ API

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

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

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

宣言的プッシュメッセージは、ユーザーエージェントが理解できるJSONドキュメントをデータにもつ プッシュメッセージです。ユーザーエージェントは、受信した プッシュメッセージごとに宣言的プッシュメッセージであるかどうかを 宣言的プッシュメッセージパーサーを使って判定します。

宣言的プッシュメッセージを利用することで、Service Worker を介さずに通知を作成・表示できます。ただし、アプリケーションサーバーの意図で Service Worker を介することもできます。そのような場合、プッシュメッセージの宣言的性質は、たとえばストレージ圧迫などで Service Worker が退去された場合のバックアップとして機能します。また、通知データの伝達によりオブジェクト指向的な手法を提供します。

{
  "web_push": 8030,
  "notification": {
    "title": "Ada emailed ‘London’",
    "lang": "en-US",
    "dir": "ltr",
    "body": "Did you hear about the tube strikes?",
    "navigate": "https://email.example/message/12"
  }
}

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

プッシュサブスクリプションには、スコープが関連付けられています。これは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-256ECDH鍵ペアを生成する [ANSI-X9-62]。 秘密鍵はsubscriptionの内部スロットに格納され、この値はアプリケーションに公開されてはなりません。 公開鍵も内部スロットに格納され、getKey()メソッドを p256dh引数で呼び出すことで取得できる。
5. 新しい認証シークレット（[RFC8291]で定義されるオクテット列）を生成する。 この認証シークレットはsubscriptionの内部スロットに格納される。 この鍵はgetKey()メソッドを 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 の サービスワーカー登録 が null なら：
   1. scope に、"/" と global の関連 DocumentのURLで基本URLパーサーを実行した結果を設定する。
6. それ以外の場合：
   1. Assert: this の サービスワーカー登録 は サービスワーカー登録である。
   2. registration に this の サービスワーカー登録を設定する。
7. 以下の手順を並行して実行する：
   Note: 検証順序はユーザーエージェントによって異なる場合があります
   1. もし scope が失敗または URLで、そのschemeが"https"でない場合、グローバルタスクをキューに入れる（networking task sourceを使い、globalでpromiseをreject、例外は"NotAllowedError" DOMException）。
   2. もし options 引数の userVisibleOnly が false であり、ユーザーエージェントが true を要求する場合、グローバルタスクをキューに入れて promise を NotAllowedError で reject。
   3. もし options 引数が applicationServerKey メンバーに非null値を含まず、プッシュサービスがそれを要求する場合、グローバルタスクをキューに入れて promise を NotSupportedError で reject。
   4. もし options 引数に applicationServerKey 属性に非null値があれば：
      1. もし options の applicationServerKey が DOMString なら、その値を base64url デコードして ArrayBuffer にする。失敗したら InvalidCharacterError で reject。
      2. デコード失敗時、グローバルタスクをキューに入れて promise を InvalidCharacterError で reject。
      3. options の applicationServerKey が P-256 曲線上の有効な点か確認し、無効なら InvalidAccessError で reject。
   5. subscription を null にする。
   6. もし scope が非nullの場合：
      1. もし プッシュサブスクリプションで、ウィンドウアクセシブルスコープの scope が scope と等しいものがあれば、subscription にそのプッシュサブスクリプションを設定する。
   7. それ以外の場合：
      1. Assert: registration が非null。
      2. もし registration の active worker が null なら、グローバルタスクをキューに入れて promise を InvalidStateError で reject。
      3. もし registration の 関連プッシュサブスクリプション が非nullなら、subscription にそれを設定する。
      4. scope に registration の scope URLを設定する。
   8. permission を "push" の利用許可を要求した結果とする。
   9. もし permission が "denied" なら、グローバルタスクをキューに入れて promise を NotAllowedError で reject。
   10. もし subscription が非nullなら：
       1. もし subscription にエラーがあれば、グローバルタスクをキューに入れて promise を AbortError で reject。
       2. options 引数の値と subscription の options 属性を比較し、BufferSource型は値の等価性比較。
       3. もし options のいずれかの属性値が subscription の保存値と異なれば、グローバルタスクをキューに入れて promise を InvalidStateError で reject。
       4. グローバルタスクをキューに入れて promise を subscription で resolve、手順終了。
   11. Assert: subscription は null かつ scope は URL。
   12. subscription に プッシュサブスクリプションを作成（options付き）した結果を設定。例外が発生した場合はその例外で promise を reject。
   13. subscription の scope に scope を設定する。
   14. グローバルタスクをキューに入れて promise を PushSubscription（subscription対応）で resolve。
8. promise を返す。

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

1. promise を 新しい promiseとする。
2. global を this の関連グローバルオブジェクトとする。
3. windowScope を null にする。
4. registration を null にする。
5. もし this の サービスワーカー登録 が null なら、windowScope に "/" と global の関連 Document の URL を使って基本URLパーサーの結果を設定。
6. それ以外の場合：
   1. Assert: this の サービスワーカー登録 は サービスワーカー登録である。
   2. registration に this の サービスワーカー登録を設定する。
7. 以下の手順を並行して実行する：
   1. subscription を null にする。
   2. もし windowScope が非nullなら：
      1. もし プッシュサブスクリプションで scope が windowScope のものがあれば、subscription にそのプッシュサブスクリプションを設定する。
   3. それ以外の場合：
      1. Assert: registration が非null。
      2. もし registration の 関連プッシュサブスクリプション が非nullなら、subscription にそれを設定する。
   4. もし subscription が null なら、promise を null で resolve。
   5. もし subscription にエラーがあれば、promise を DOMException（名前は "AbortError"）で reject、手順終了。
   6. promise を PushSubscription（subscription対応）で resolve。
8. promise を返す。

permissionState() メソッドは呼び出されたとき、以下の手順を必ず実行します：

1. promise を 新しい promiseで作成。
2. promise を返し、以降の手順は非同期で継続。
3. descriptor を新しい PermissionDescriptor にし、name を "push" で初期化。
4. state を descriptor の permission stateとして取得。
5. promise を state で resolve。

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

許可を求める必要がある場合は、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] Annex A で記載された非圧縮形式（先頭0x04オクテット、合計65オクテット）でエンコードされていなければなりません。 DOMString として提供する場合は、 必ず base64urlエンコード [RFC7515] でエンコードしてください。

ユーザーエージェントは applicationServerKeyが存在しない場合で、プッシュサービスが運用上要求する場合、購読試行を拒否してもよいです。

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;
};