通知API

設定オブジェクトを用いて通知を作成 するには、文字列title、 NotificationOptions 辞書options、および 環境設定オブジェクトsettingsが与えられたとき：

1. originをsettingsの オリジンとする。

2. baseURLをsettingsの API基底URLとする。

3. fallbackTimestampを、Unix エポックから settingsの現在の壁時計時刻までのミリ秒数を、 最も近い整数に丸めたものとする。

4. 通知を作成するときに、title、 options、origin、baseURL、およびfallbackTimestampを与えた結果を返す。

作成する 通知を、文字列title、 NotificationOptions 辞書options、オリジン origin、URLbaseURL、およびEpochTimeStamp fallbackTimestampが与えられたとき：

1. notificationを新しい通知とする。

2. options["renotify"]が trueであり、かつ options["tag"]が 空文字列である場合、例外を投げる： TypeError。

3. notificationのデータを StructuredSerializeForStorage(options["data"])に設定する。

4. notificationのタイトルをtitleに設定する。

5. notificationの方向を options["dir"]に設定する。

6. notificationの言語を options["lang"]に設定する。

7. notificationのオリジンをoriginに設定する。

8. notificationの本文を options["body"]に設定する。

9. options["navigate"]が 存在する場合、 構文解析する際にbaseURLを使用し、その結果が 失敗でなければ、 notificationのナビゲーションURLを戻り値に設定する。(それ以外の場合、 notificationのナビゲーションURLはnullのままとなる。)

10. notificationのタグを options["tag"]に設定する。

11. options["image"]が 存在する場合、 構文解析する際にbaseURLを使用し、その結果が 失敗でなければ、 notificationの画像 URLを戻り値に設定する。(それ以外の場合、 notificationの画像URLは設定されない。)

12. options["icon"]が 存在する場合、 構文解析する際にbaseURLを使用し、その結果が 失敗でなければ、 notificationのアイコン URLを戻り値に設定する。(それ以外の場合、 notificationのアイコン URLは設定されない。)

13. options["badge"]が 存在する場合、 構文解析する際にbaseURLを使用し、その結果が 失敗でなければ、 notificationのバッジ URLを戻り値に設定する。(それ以外の場合、 notificationのバッジURLは設定されない。)

14. options["timestamp"]が 存在する場合、 notificationのタイムスタンプをその値に設定する。それ以外の場合、 notificationのタイムスタンプをfallbackTimestampに設定する。

15. notificationの再通知設定を options["renotify"]に設定する。

16. notificationのサイレント設定を options["silent"]に設定する。

17. notificationの操作必須設定を options["requireInteraction"]に設定する。

18. notificationのアクションを« »に設定する。

19. options["actions"]内の各entryについて、 次の上限まで 最大アクション数としてサポートされる数だけ処理する (上限を超える エントリはスキップする)：

    1. actionを新しい通知アクションとする。

    2. actionの名前を entry["action"]に設定する。

    3. actionのタイトルを entry["title"]に設定する。

    4. entry["navigate"]が 存在する場合、 構文解析する際にbaseURLを使用し、その結果が 失敗でなければ、 actionのナビゲーションURLを戻り 値に設定する。 (それ以外の場合、actionのナビゲーションURLはnullのままとなる。)

    5. entry["icon"]が 存在する場合、 構文解析する際にbaseURLを使用し、その結果が 失敗でなければ、 actionのアイコンURLを戻り値に設定する。(それ以外の場合、 actionのアイコンURLはnullのままとなる。)

    6. actionをnotificationのアクションに追加する。

20. notificationを返す。

通知の権限状態を取得するには、次の 手順を実行する：

1. permissionStateを、現在の権限 状態を取得するときに、 "notifications"を指定した結果とする。

2. permissionStateが"prompt"である場合、"default"を返す。

3. permissionStateを返す。

フェッチ手順は、 通知notificationと、nullまたは 環境設定オブジェクトsettingsが与えられたとき、次のとおりである：

1. 通知プラットフォームが画像をサポートし、notificationの 画像URLが設定されている場合、通知リソースをフェッチする。その際に、 notification、notificationの画像URL、 settings、およびリソースresourceが与えられたときの次の手順を与える： notificationの画像リソースをresourceに設定する。

2. 通知プラットフォームがアイコンをサポートし、notificationの アイコンURLが設定されている場合、通知リソースをフェッチする。その際に、 notification、notificationのアイコンURL、 settings、およびリソースresourceが与えられたときの次の手順を与える： notificationのアイコンリソースをresourceに設定する。

3. 通知プラットフォームがバッジをサポートし、notificationの バッジURLが設定されている場合、通知リソースをフェッチする。その際に、 notification、notificationのバッジURL、 settings、およびリソースresourceが与えられたときの次の手順を与える： notificationのバッジリソースをresourceに設定する。

4. 通知プラットフォームがアクションとアクションアイコンをサポートする場合、 各actionについて、notificationの アクションを反復する： actionのアイコンURLが nullでない場合、通知リソースをフェッチする。その際に、 notification、 actionのアイコンURL、settings、および リソースresourceが与えられたときの次の手順を与える：actionの アイコン リソースをresourceに設定する。

フェッチする 通知リソースを、通知 notification、URLurl、nullまたは 環境設定オブジェクトsettings、および アルゴリズム processResource (リソースを受け取るもの) が与えられたとき：

1. requestを新しいリクエストとする。そのURLは url、クライアントはsettings、宛先は "image"、モードは"no-cors"、および 資格情報モードは "include"とする。

2. settingsがnullである場合、requestのオリジンを notificationのオリジンに、requestの リファラーを"no-referrer"に、および requestの サービスワーカーモードを"none"に設定する。

   これは、ユーザーエージェントが宣言型プッシュ メッセージの 通知を表示する場合に該当する。そのような通知のリソースは、 サービスワーカーを介さずにフェッチされる。宣言型プッシュメッセージは、 それを必要としないように設計されているためである。 [PUSH-API]

3. フェッチする際に、requestのuseParallelQueueをtrueに設定し、 processResponseConsumeBodyを、 次のものが与えられたときの以下の手順に設定する： レスポンスresponseと、null、失敗、または バイト列bytes：

   1. bytesがnullまたは失敗である場合、戻る。

   2. bytesを画像として復号することを試みる。

   3. その画像形式がサポートされている場合、復号された リソースを与えてprocessResourceを実行する。

   この意図は、このリソースを <img>と同様にフェッチすることであるが、 これには抽象化が必要である。

通知 表示手順は、通知 notificationと、nullまたは環境設定オブジェクトsettingsが与えられたとき、 次のとおりである：

1. フェッチ手順を、 notificationとsettingsを与えて実行する。

2. すべてのフェッチの完了と、notificationの 画像リソース、 アイコンリソース、および バッジリソースが 設定されること (ある場合)、ならびに アイコン リソース (対象はnotificationの アクション) が設定されること (ある場合) を待つ。

3. shownをfalseとする。

4. oldNotificationを、通知のうち、 リスト 内の通知であって、そのタグが 空文字列でなく、かつ notificationのタグと等しく、 そのオリジンが 同一オリジンであるもの (比較対象はnotificationのオリジン) とする。そのような通知があればそれを使用し、 nullとするのは それ以外の場合である。

5. oldNotificationがnullでない場合：

   1. クローズイベントを処理する。その際に、 oldNotificationを与える。

   2. 通知プラットフォームが置き換えをサポートする場合：

      1. 置き換える。oldNotificationを notificationに、次の 通知リスト内で置き換える。

      2. shownをtrueに設定する。

      通知プラットフォームには、 ネイティブの 置き換えをサポートすることが強く推奨される。これは、ユーザー体験の向上につながるためである。

   3. それ以外の場合、削除する。oldNotificationを次の 通知リストから削除する。

6. shownがfalseである場合：

   1. 追加する。notificationを通知リストに追加する。

   2. notificationをデバイス上に表示する (例えば、適切な 通知プラットフォームAPIを呼び出すことによって)。

7. shownがfalse、またはoldNotificationがnullでなく、かつ notificationの再通知設定がtrueである場合、任意で、 ユーザーエージェントが定義する方法でエンドユーザーに注意を促す (例えば、音を鳴らすことによって)。

8. notificationが非永続通知である場合、タスクをキューに入れる。 そのタスクでは、イベントを発火する。名前はshowとし、対象はNotification オブジェクトであり、それが表すのは notificationである。

通知notification、またはその アクションのいずれかがエンドユーザーによってアクティブ化されたとき、 基盤となる通知 プラットフォームがアクティブ化をサポートすることを前提として、ユーザーエージェントは (別途指定がない限り) 次の手順を実行しなければならない：

1. actionをnullとする。

2. notificationのアクションのいずれかがエンド ユーザーによってアクティブ化された場合、actionをその通知アクションに設定する。

3. navigationURLをnotificationの ナビゲーションURLとする。

4. actionがnullでない場合、navigationURLをactionの ナビゲーションURLに設定する。

   これは、通知アクションの ナビゲーションURLがnullである場合に、処理が 次の clickイベントへ進むよう意図的にしており、Web開発者により大きな柔軟性を提供する。

5. navigationURLがnullでない場合：

   1. 次の2つの選択肢のうち1つを、実装定義の方法で選択する：

      • ナビゲートする。既存のトップレベル走査可能体で、ユーザー エージェントのトップレベル走査可能体集合内にあるものを、 navigationURLへナビゲートする。

      • 新しいトップレベル 走査可能体を作成する。その際にnavigationURLを与える。

      ユーザーエージェントには、プラットフォームの 慣例に合わせることが強く推奨される。

   2. 戻る。

6. notificationが永続通知である場合：

   1. actionNameを空文字列とする。

   2. actionがnullでない場合、actionNameをactionの 名前に設定する。

   3. サービスワーカー通知 イベントを発火する。名前を"notificationclick"とし、 notificationとactionNameを与える。

7. それ以外の場合、タスクをキューに入れる。そのタスクは次の手順を実行する：

   1. intoFocusを、イベントを発火するときの結果とする。名前を clickとし、対象はNotification オブジェクト (それが表すのはnotification) とし、その cancelable 属性をtrueに初期化する。

      ユーザーエージェントには、focus() がイベント リスナー内で動作するようにすることが推奨される。そのイベントの名前はclickである。

   2. intoFocusがtrueである場合、ユーザーエージェントは、 notificationに関連する閲覧コンテキストのビューポートにフォーカスを移すべきである。

Webプラットフォーム全体で、「アクティブ化」は意図的に「クリック」と誤った名前で呼ばれている。

クローズ手順は、 与えられた通知notificationについて、次のとおりである：

1. 通知リストが含んでいない場合、 notificationを、この手順を中止する。

2. 処理する クローズイベントを。その際にnotificationを与える。

3. 削除する。notificationをリスト (通知の)から削除する。

クローズ イベントを処理するには、通知notificationが与えられたとき：

1. notificationが永続通知であり、かつ notificationが エンドユーザーによって閉じられた場合、サービスワーカー通知 イベントを発火する。名前を "notificationclose"とし、notificationを与える。

2. notificationが非永続通知である場合、タスクをキューに入れる。 そのタスクでは、イベントを発火する。名前はcloseとし、対象はNotification オブジェクトであり、それが表すのは notificationである。

[Exposed=(Window,Worker)]
interface Notification : EventTarget {
  constructor(DOMString title, optional NotificationOptions options = {});

  static readonly attribute NotificationPermission permission;
  [Exposed=Window] static Promise<NotificationPermission> requestPermission(optional NotificationPermissionCallback deprecatedCallback);

  static readonly attribute unsigned long maxActions;

  attribute EventHandler onclick;
  attribute EventHandler onshow;
  attribute EventHandler onerror;
  attribute EventHandler onclose;

  readonly attribute DOMString title;
  readonly attribute NotificationDirection dir;
  readonly attribute DOMString lang;
  readonly attribute DOMString body;
  readonly attribute USVString navigate;
  readonly attribute DOMString tag;
  readonly attribute USVString image;
  readonly attribute USVString icon;
  readonly attribute USVString badge;
  readonly attribute EpochTimeStamp timestamp;
  readonly attribute boolean renotify;
  readonly attribute boolean? silent;
  readonly attribute boolean requireInteraction;
  [SameObject] readonly attribute any data;
  [SameObject] readonly attribute FrozenArray<NotificationAction> actions;

  undefined close();
};

dictionary NotificationOptions {
  NotificationDirection dir = "auto";
  DOMString lang = "";
  DOMString body = "";
  USVString navigate;
  DOMString tag = "";
  USVString image;
  USVString icon;
  USVString badge;
  EpochTimeStamp timestamp;
  boolean renotify = false;
  boolean? silent = null;
  boolean requireInteraction = false;
  any data = null;
  sequence<NotificationAction> actions = [];
};

enum NotificationPermission {
  "default",
  "denied",
  "granted"
};

enum NotificationDirection {
  "auto",
  "ltr",
  "rtl"
};

dictionary NotificationAction {
  required DOMString action;
  required DOMString title;
  USVString navigate;
  USVString icon;
};

callback NotificationPermissionCallback = undefined (NotificationPermission permission);

new Notification(title, options) コンストラクターの手順は、次のとおりである：

1. thisの関連するグローバルオブジェクトがServiceWorkerGlobalScope オブジェクトである 場合、例外を投げる。その例外はTypeErrorとする。

2. options["actions"]が 空でない場合、 例外を投げる。その例外はTypeErrorとする。

   アクションは、永続 通知に対してのみサポートされる。

3. notificationを、次の結果とする： 設定 オブジェクトを用いて通知を作成する際に、title、options、 およびthisの関連する設定オブジェクトを与えた結果。

4. thisをnotificationに関連付ける。

5. 次の手順を並列に実行する：

   1. 通知の権限 状態を取得する結果が "granted"でない場合、タスクをキューに入れる。そのタスクではイベントを発火する。その名前は error、対象はthisとし、 この手順を中止する。

   2. 通知表示手順を実行する。その際に、 notificationと thisの関連する設定オブジェクトを与える。

静的なpermission取得子の手順は、 通知の権限状態を取得する結果を返すことである。

const permission = await navigator.permissions.query({name: "notifications"});
if (permission.state === "granted") {
   // APIを使用する権限がある…
}

静的な requestPermission(deprecatedCallback) メソッドの手順は、次のとおりである：

1. globalを現在のグローバルオブジェクトとする。

2. promiseを新しい プロミスとする。その作成先はthisの関連するレルムとする。

3. 次の手順を並列に実行する：

   1. permissionStateを、次の結果とする： 使用する権限を要求する際に、"notifications"を指定した結果。

   2. グローバルタスクをキューに入れる。そのDOM操作タスクソースに対して、 globalを与え、 次の手順を実行する：

      1. deprecatedCallbackが与えられている場合、呼び出す。 deprecatedCallbackを« permissionState »と "report"を指定して呼び出す。

      2. 解決をpromiseに対して、 permissionStateを値として行う。

4. promiseを返す。

var not = new Notification("Paul KalkbrennerによるGebrünn Gebrünn", { icon: "newsong.svg", tag: "song" });
not.onclick = function() { displaySong(this); };

self.registration.showNotification("Aliceからの新着メール", {
  actions: [{action: 'archive', title: "アーカイブ"}]
});

self.addEventListener('notificationclick', function(event) {
  event.notification.close();
  if (event.action === 'archive') {
    silentlyArchiveEmail();
  } else {
    clients.openWindow("/inbox");
  }
}, false);

インスタンス 1                                   | インスタンス 2
                                             |
// インスタンスが新着メールに気付く。       |
new Notification("John Doeからの新着メール",   |
                 { tag: 'message1' });       |
                                             |
                                             |  // 少し後に、このインスタンスが気付く
                                             |  // 新着メールがあることに。
                                             |  new Notification("John Doeからの新着メール",
                                             |                   { tag: 'message1' });

// Bobが"こんにちは"と言う
new Notification("Bob: こんにちは", { tag: 'chat_Bob' });

// Bobが"今日の午後は空いている？"と言う
new Notification("Bob: こんにちは / 今日の午後は空いている？", { tag: 'chat_Bob' });

dictionary GetNotificationOptions {
  DOMString tag = "";
};

partial interface ServiceWorkerRegistration {
  Promise<undefined> showNotification(DOMString title, optional NotificationOptions options = {});
  Promise<sequence<Notification>> getNotifications(optional GetNotificationOptions filter = {});
};

[Exposed=ServiceWorker]
interface NotificationEvent : ExtendableEvent {
  constructor(DOMString type, NotificationEventInit eventInitDict);

  readonly attribute Notification notification;
  readonly attribute DOMString action;
};

dictionary NotificationEventInit : ExtendableEventInit {
  required Notification notification;
  DOMString action = "";
};

partial interface ServiceWorkerGlobalScope {
  attribute EventHandler onnotificationclick;
  attribute EventHandler onnotificationclose;
};

showNotification(title, options) メソッドの手順は、次のとおりである：

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

2. promiseを新しい プロミスとする。その作成先はthisの関連するレルムとする。

3. thisのアクティブなワーカーがnullである場合、 却下をpromiseに対してTypeError を理由として行い、promiseを返す。

4. notificationを、次の結果とする： 設定 オブジェクトを用いて通知を作成する際に、title、options、 およびthisの関連する設定オブジェクトを与えた結果。これが 例外を投げた場合、 却下をpromiseに対してその例外を理由として行い、 promiseを返す。

5. notificationのサービスワーカー登録を thisに設定する。

6. 次の手順を並列に実行する：

   1. 通知の権限 状態を取得する結果が "granted"でない場合、グローバルタスクをキューに入れる。その際に、 DOM操作タスクソース上で、 globalを与え、却下を promiseに対してTypeErrorを理由として行う。 そして、この手順を中止する。

   2. 通知表示手順を実行する。その際に、 notificationと thisの関連する設定オブジェクトを与える。

   3. notificationのサービスワーカー登録の 呼び出し済みかどうか、 showNotification()が正常に をtrueに設定する。

   4. グローバルタスクをキューに入れる。そのDOM操作タスクソースに対して、 globalを与え、解決を promiseに対してundefinedを値として行う。

7. promiseを返す。

getNotifications(filter) メソッドの手順は、次のとおりである：

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

2. realmをthisの関連するレルムとする。

3. originをthisの関連する設定オブジェクトの オリジンとする。

4. promiseを新しい プロミスとし、realm内に作成する。

5. 次の手順を並列に実行する：

   1. tagをfilter["tag"]とする。

   2. notificationsをリストとする。その要素は、すべての通知のうち、 通知リスト内にあり、そのオリジンが、 同一オリジンであるもの (比較対象は origin) で、そのサービスワーカー登録がthisであり、 そのタグが、tagが 空文字列でない場合には、tagと等しいものとする。

   3. グローバルタスクをキューに入れる。そのDOM操作タスクソースに対して、 globalを与え、 次の手順を実行する：

      1. objectsをリストとする。

      2. 各通知について、 notificationsを作成 順に反復し、新しいNotification オブジェクトをrealmで作成する。それが表すのは、 通知であり、追加する対象をそのオブジェクト、追加先をobjectsとする。

      3. 解決をpromiseに対して、 objectsを値として行う。

6. promiseを返す。

このメソッドは、0個以上の新しいNotification オブジェクトを返す。これらは、 同じ基盤となる通知を、Notification オブジェクト (すでに存在するもの) と共有して表す場合がある。

サービスワーカー通知イベントを発火するには、名前 name、および 通知notificationと、省略可能な文字列 action (既定値は 空文字列) が与えられたとき、機能イベントを発火する手順を、name、NotificationEvent、 notificationのサービスワーカー登録、および次の 初期化を与えて実行する：

notification

新しいNotification オブジェクトで、notificationを表すもの。

action

action

notification取得子の手順は、 次のことを行う： 初期化時に設定された値を返す。

action取得子の手順は、返すことである、 その 初期化時に設定された値を。