CyberLibrarian

【注意】 このドキュメントは、W3CのWeb Notifications W3C Recommendation 22 October 2015の和訳です。
このドキュメントの正式版はW3Cのサイト上にある英語版であり、このドキュメントには翻訳に起因する誤りがありえます。誤訳、誤植などのご指摘は、訳者までお願い致します。

First Update: 2018年1月5日

W3C

ウェブ通知

W3C勧告 2015年10月22日

本バージョン:
http://www.w3.org/TR/2015/REC-notifications-20151022/
最新バージョン:
http://www.w3.org/TR/notifications/
バージョン履歴:
http://dvcs.w3.org/hg/notifications/shortlog
旧バージョン:
http://www.w3.org/TR/2015/PR-notifications-20150910/
http://www.w3.org/TR/2015/CR-notifications-20150519/
http://www.w3.org/TR/2013/WD-notifications-20130912/
http://www.w3.org/TR/2012/WD-notifications-20120614/
http://www.w3.org/TR/2011/WD-notifications-20110301/
(前)編集者:
John Gregg (Google) <johnnyg@google.com>
編集者(https://notifications.spec.whatwg.org/バージョン):
Anne van Kesteren (Mozilla) <annevk@annevk.nl>

公開以後に報告されたエラーや問題がないか正誤表を確認してください。

この仕様の英語版が唯一の規範のバージョンです。非規範の翻訳版も入手可能かもしれません。

Copyright © 2015 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.

要約

ウェブ通知は、エンドユーザ通知のためのAPIを定義しています。通知により、Eメールの配信など、表示されているウェブ・ページの外部でユーザに通報を行うことができます。

このドキュメントのステータス

この項は、このドキュメントの公開時のステータスについて記述しています。他のドキュメントがこのドキュメントに取って代わることがありえます。現行のW3Cの刊行物およびこの技術報告の最新の改訂版のリストは、http://www.w3.org/TR/のW3C技術報告インデックスにあります。

これは、ウェブ通知のW3C勧告です。

このドキュメントは、W3Cメンバー、ソフトウェア開発者、他のW3Cグループ、および他の利害関係者によりレビューされ、W3C勧告として管理者の協賛を得ました。これは確定済みドキュメントであり、参考資料として用いたり、別のドキュメントで引用したりすることができます。勧告の作成におけるW3Cの役割は、仕様に注意を引き付け、広範囲な開発を促進することです。これによってウェブの機能性および相互運用性が増強されます。

W3Cウェブ通知ワーキンググループは、W3C勧告として、この仕様の公開に責任があるW3Cワーキンググループでした。このドキュメントに関してコメントを行いたい場合には、public-web-notification@w3.org(購読、アーカイブ)にお送りください。

W3Cは、この勧告で規定されている機能は、[DOM4]や[WEBIDL]の仕様が勧告になっても、それらの変更の影響を受けれないものと予想しています。

この仕様のテスト・スイートおよび実装報告書も参照してください。

通知の仕様は、https://notifications.spec.whatwg.org/でも開発されています。そこでの最近の作業は、通知をService Workerおよびその他の新しい機能と統合することを中心に行われています。また、その仕様では、この仕様に含まれているonshowとoncloseのイベントには十分なユースケースがないという理由で、非推奨とされています。

このドキュメントは、2004年2月5日のW3C特許方針の下で活動しているグループによって作成されました。W3Cは、このグループの成果物に関連するあらゆる特許の開示の公開リストを維持し、このページには特許の開示に関する指示も含まれています。不可欠な請求権(Essential Claim(s))を含んでいると思われる特許に関して実際に知っている人は、W3C特許方針の6項に従って情報を開示しなければなりません。

このドキュメントは、2015年9月1日のW3Cプロセス・ドキュメントによって管理されています。

目次

1 はじめに

この仕様は、ウェブ・ページの外部で通知を表示してユーザに通報を行うためのAPIを提供します。この仕様で「デスクトップ」での通知の表示について言及する時は、一般的にウェブ・ページの外部にある静的な表示領域を意味しますが、次のものを含むいくつかの形を取る可能性があります。

ここでは、ユーザ・エージェントがこれらの通知を表示すべき方法を厳密に規定しません。最も良い表示方法は、ユーザ・エージェントが動作するデバイスに依存します。APIは、表示のオプションに対して柔軟であるように設計されています。

この仕様は、きるかぎり既存の通知プラットフォームと互換性を持つように設計されていますが、プラットフォームに依存しないようにも設計されています。一般的なプラットフォームが同じ機能を提供するとは限らないため、この仕様では、どのようなイベントが保証されるのかされないのかを示します。特に、ここで規定している通知には、テキストとアイコンのコンテンツしか含めることができません。

一般的に、通知のイベント・モデルはベスト・エフォート型です。Notificationオブジェクトはclickというイベントを提供しており、アプリケーションは、そのイベントに従うことで機能を強化できますが、基礎となる通知プラットフォームがその機能を提供していない場合もあるため、それを受信することを当てにすることはできません。

2 適合性

非規範的と明示しているすべての項と同じく、この仕様のすべての図、例、注は、非規範的です。この仕様のその他の部分はすべて規範的です。

この仕様の規範的な部分の「しなければならない(MUST)」、「してはならない(MUST NOT)」、「必須である／要求される(REQUIRED)」、「すべきである／する必要がある(SHOULD)」、「すべきでない／する必要がない(SHOULD NOT)」、「推奨される(RECOMMENDED)」、「することができる／してもよい(MAY)」、「選択できる／任意である(OPTIONAL)」というキーワードは、RFC2119で記述されているように解釈されるべきです。読みやすさのために、これらの用語をすべて大文字で表しているとは限りません。[RFC2119]

2.1 セキュリティ

通知は、ユーザが希望することを示した時にのみ出すべきです。そうでないと、ユーザにとって良くない経験を作り出すことになりえます。

3 用語

この仕様で用いている専門用語のほとんどは、DOM、HTML、IDL、URLからのものです。[DOM4] [HTML5] [WEBIDL] [URL]

4 モデル

通知により、Eメールの配信など、何かが発生したということをウェブ・ページの外部でユーザに通報することができます。

個々の通知には、タイトル(title)、方向(direction)、言語(language)、およびオリジン(origin)があります。

個々の通知は、関連する本文(body)、タグ(tag)、アイコンURL(icon URL)、アイコン画像(icon image)を持つことができます。

開発者は、エンドユーザが別の手段ではアクセスできない形で、アイコン、音声、または振動パターンにより情報を伝達しないことをお勧めします。詳細はWCAGを参照してください。

4.1 方向

この項は、HTMLの表示(Rendering)の項で用いられているものと同等の用語で記述しています。[HTML5]

ユーザ・エージェントは、通知のタイトルと本文のテキストのUnicodeのセマンティクスを尊重することが求められます。例えば、U+000A LINE FEED (LF)の文字の段落区切りの動作をサポートするなど、双方向アルゴリズムの規則P1、P2、P3で定義されているとおりに、それぞれが表示される際に、1つ以上の双方向アルゴリズムの段落の独立した集合として扱われることが期待されます。タイトルと本文の段落ごとに、通知の方向は、その値が「auto」(自動)以外になっていれば、規則P2とP3の高レベルな上書きを提供します。[BIDI]

4.2 言語

通知の言語は、通知のタイトルと本文の主要言語を規定します。その値は、有効なBCP 47言語タグまたは空の文字列です。空の文字列は主要言語が未知であることを示します。[LANG]

4.3 許可

通知は、ユーザ(または、ユーザの代理としてユーザ・エージェント)が許可を与えた場合にのみ表示できます。あるオリジンの通知を表示する許可は、次の3つの文字列のいずれかでありえます。

「default」(デフォルト)

これは、「denied」(拒否)と同等ですが、ユーザはこれまでに明示的な選択を行っていません。

「denied」(拒否)

これは、ユーザが通知を望まないことを意味します。

「granted」(許可)

これは、通知を表示できることを意味します。

「granted」を意味する「default」に当たる文字列はありません。その場合、アプリケーションが許可を求める理由がないため、単に「granted」が返されます。

4.4 通知リスト

ユーザ・エージェントは、保留中の通知のリストおよびアクティブな通知のリストを保持しなければなりません。

4.5 通知を提示する

あるnotificationの提示テップは次のとおりです。

  1. notificationのオリジンの許可が「granted」でない場合、通知のアイコンURLに対して行っている取得をキャンセルし、notification上でerrorというイベントを発火させるタスクをキューに入れ、これらのステップを終了させます。

  2. タグがnotificationのタグと同じで、オリジンがnotificationのオリジンと同じである保留中の通知のリストまたはアクティブな通知のリストに通知がある場合、その通知とnotificationの置換ステップを実行し、その後にこれらのステップを終了させます。

  3. デバイスに同時通知数の制限がなく、直ちに通知を表示できる場合、表示ステップを実行し、これらのステップを終了させます。

  4. デバイスに同時通知数の制限があれば、キューをネイティブにサポートする通知プラットフォームを直ちに呼び出すか、保留中の通知のリストにnotificationを追加するかのいずれかを行います。

4.6 通知を起動する

ユーザが通知のnotificationを起動した時には、基礎となる通知プラットフォームが起動をサポートしていると仮定すると、ユーザ・エージェントは、notificationを表すNotificationオブジェクトごとに、Notificationオブジェクト上でclickというイベントを発火させるタスクをキューに入れなければなりません。

ウェブ・プラットフォームでは、至る所で「起動」は意図的に「クリック」という間違った名で呼ばれます。

ユーザ・エージェントは、通知に関連するブラウジング・コンテキストをフォーカスさせる手段として、clickというイベントのイベント・リスナー内からwindow.focus()を動作させることを強く推奨します。

4.7 通知を閉じる

基礎となる通知プラットフォームまたはユーザによって通知が閉じられる場合は、そのための終了ステップが実行されなければなりません。

あるnotificationの終了ステップは次のとおりです。

  1. notificationが保留中の通知のリストにもアクティブな通知のリストにもなければ、これらのステップを終了させます。

  2. 保留中の通知のリストまたはアクティブな通知のリストからnotificationを削除するタスクをキューに入れ、notification上でcloseというイベントを発火させます。

4.8 通知を保留する

保留中の通知のリストが空でない時には、ユーザ・エージェントは常にデバイス上の利用可能な通知スペースの変更を待ち、監視しなければなりません。

例えば、以前の通知が却下されたなどの理由で、デバイス上の利用可能な表示スペースが新しい通知を表示できるように変更された場合、ユーザ・エージェントは、保留中の通知のリストの最初の通知に対して表示ステップを実行し、その後にそれを保留中の通知のリストから削除すべきです。

4.9 通知を表示する

あるnotificationの表示ステップは次のとおりです。

  1. 通知プラットフォームがアイコンをサポートしていて、notificationのアイコンURLが設定されているけれどもまだ取得していない場合、それを取得して資源が完全にダウンロードされるのを待ちます。

    取得が終了し、画像フォーマットがサポートされていれば、notificationのアイコン画像をデコードされた資源に設定します。

  2. タスクをキューに入れて次のサブステップを実行します。

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

    2. 表示が失敗した(例えば、通知プラットフォームがエラーを返した)場合、notification上でerrorというイベントを発火させ、これらのステップを終了させます。

    3. アクティブな通知のリストにnotificationを追加します。

    4. notification上でshowというイベントを発火させます。

4.10 通知を置き換える

old(古い)通知をnew(新しいもの)に置き換えるための置換ステップは次のとおりです。

  1. 通知プラットフォームがアイコンをサポートしていて、newのアイコンURLが設定されているけれどもまだ取得していない場合、それを取得して資源が完全にダウンロードされるのを待ちます。

    取得が終了し、画像フォーマットがサポートされていれば、newのアイコン画像をデコードされた資源に設定します。

  2. 保留中の通知のリストにoldがある場合、保留中の通知のリストのoldをnewに同じ位置で置き換えるタスクをキューに入れ、old上でcloseというイベントを発火させます。

  3. そうでない場合は、アクティブな通知のリストのoldをnewに同じ位置で置き換えるタスクをキューに入れ、old上でcloseというイベントを発火させ、new上でshowというイベントを発火させます。

    通知プラットフォームが置換をサポートしていない場合、この要件は、oldに対して終了ステップを実行し、その後にnewに対して表示ステップを実行することで対処できます。

    通知プラットフォームがネイティブな置換をサポートすることを強く推奨します。そのほうがはるかに良いです。

5 API

通知はNotificationオブジェクトで表され、そのコンストラクタにより作成できます。 

[Constructor(DOMString title, optional NotificationOptions options)]
interface Notification : EventTarget {
  static readonly attribute NotificationPermission permission;
  static void requestPermission(optional NotificationPermissionCallback callback);

  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 DOMString tag;
  readonly attribute DOMString icon;

  void close();
};

dictionary NotificationOptions {
  NotificationDirection dir = "auto";
  DOMString lang = "";
  DOMString body;
  DOMString tag;
  DOMString icon;
};

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

callback NotificationPermissionCallback = void (NotificationPermission permission);

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

Notification(title, options)コンストラクタは、次のステップを実行しなければなりません。

  1. notificationを、Notificationオブジェクトにより表される新しい通知とします。

  2. notificationのタイトルをtitleに設定します。

  3. notificationの方向をoptionsのdirに設定します。

  4. optionsのlangが有効なBCP 47言語タグまたは空の文字列である場合、notificationの言語をoptionsのlangに設定します。そうでない場合は、それを空の文字列に設定します。[LANG]

  5. notificationsのオリジンを現在のオリジンに設定します。

  6. optionsのbodyが存在している場合、notificationの本文をbodyに設定します。

  7. optionsのtagが存在している場合、notificationのタグをtagに設定します。

  8. optionsのiconが存在している場合、エントリー設定オブジェクトにより指定されているAPI基底URLを用いてiconを解析し、それが、失敗を返さなければ、notificationのアイコンURLを返り値に設定します。

  9. notificationを返しますが、これらのステップを非同期的に実行し続けます。

  10. アイコンURLが設定されていて、通知プラットフォームがアイコンをサポートしていれば、ユーザ・エージェントは、この時点でnotificationのアイコンURLを取得し始めることができます。

  11. notificationに対して提示テップを実行します。

静的なpermission属性は、許可を返さなければなりません。

静的なrequestPermission(callback)メソッドは、次のステップを実行しなければなりません。

  1. 返しますが、これらのステップを非同期的に実行し続けます。

  2. permissionをpermissionとします。

  3. permissionが「default」である場合、現在のオリジンに対する通知の提示を受け入れられるかをユーザに質問します。受け入れられる場合は、permissionを「granted」に設定し、そうでない場合は「denied」に設定します。

  4. 許可をpermissionに設定するタスクをキューに入れ、callbackが与えられていれば、permissionを持つcallbackを1つの引数として呼び出します。

設計時には、これまでのところ、プラットフォーム通知が、ユーザに事前に質問することが妥当である場合の唯一の事例です。他のAPIの仕様にはこのパターンを用いるべきではなく、その代わりに、多くのより適当な選択肢の1つを用いるべきです。

以下は、Notificationオブジェクトに属性としてサポートされていなければならないイベント・ハンドラ(そして、その対応するイベント・ハンドラ・イベント型)です。

イベント・ハンドラ イベント・ハンドラ・イベント型
onclick click
onshow show
onerror error
onclose close

close()メソッドは、通知に対し終了ステップを実行しなければなりません。

title属性は、通知のタイトルを返さなければなりません。

dir属性は、通知の方向を返さなければなりません。

lang属性は、通知の言語を返さなければなりません。

body属性は、通知の本文を返さなければならず、そうでない場合は、空の文字列を返さなければなりません。

tag属性は、通知のタグを返すか、タグがない場合は空の文字列を返さなければなりません。

icon属性は、(シリアル化された)通知のアイコンURLを返さなければならず、そうでない場合は、空の文字列を返さなければなりません。

6 例

6.1 イベントの使用

Notificationオブジェクトは、そのライフサイクル中にイベントを送り、開発者は、望ましい動作を生成するためにそれを使用できます。

showイベントは、ユーザに通知が提示される時に送られます — これは、表示スペースが限られていてキューが1つである場合に、通知作成後のある時点でありえます。

次の例では、このイベントは、通知がいつ提示されたかに関わらず、15秒間だけ表示されることを保証するために用いられています。 

var notification = new Notification("New Email Received", { icon: "mail.png" })
notification.onshow = function() { setTimeout(notification.close, 15000) }

ユーザによって通知が却下された場合には、closeイベントが送られます。開発者は、通知が認められた場合にアクションを実行するために、このイベントを使用できます。

次の例では、会議のリマインダ通知が認められれば、アプリケーションはその他の形式のリマインダを抑制します。 

var notification = new Notification("Meeting about to begin", { icon: "calendar.gif", body: "Room 101" })
notification.onclose = function(event) { cancelReminders(event) }

6.2 複数のインスタンスに対するtagメンバーの使用

ユーザが複数のブラウザ・タブでメール・アプリケーションを開く場合など、ウェブ・アプリケーションは、複数のインスタンスで同時に動作することがよくあります。デスクトップは共用資源であるため、通知APIは、tagメンバーを用いることで、これらのインスタンスを容易に調整できる方法を提供します。

同じ概念のイベントを表す複数の通知は、同じ方法でタグ付けすることができ、両方が提示された場合には、ユーザは通知を1つだけ受信します。

インスタンス 1                               | インスタンス 2
                                             |
// 新規メールの存在をインスタンスが通知。    |
new Notification("New mail from John Doe",   |
                 { tag: 'message1' });       |
                                             |
                                             |  // 少し後で、このインスタンスは、
                                             |  // 新規メールの存在を通知。
                                             |  new Notification("New mail from John Doe",
                                             |                   { tag: 'message1' });

ユーザ・エージェントがここのアルゴリズムに従っていれば、この状況の結果は、「John Doeからの新規メール」という1件の通知となります。

6.3 1つのインスタンスに対するtagメンバーの使用

tagメンバーは、状態の変化に応じて通知をできる限り最新のものにしておくために、アプリケーションの1つのインスタンスで用いることもできます。

例えば、AliceがBobとチャット・アプリケーションを利用していて、Aliceがアイドル状態の間にBobが複数のメッセージを送信した場合、アプリケーションは、メッセージごとにAliceがデスクトップ通知を見ないことを好むかもしれません。 

// Bobが「Hi」(やあ)と言う。
new Notification("Bob: Hi", { tag: 'chat_Bob' });

// Bobが「Are you free this afternoon?」(今日の午後、空いてる?)と言う。
new Notification("Bob: Hi / Are you free this afternoon?", { tag: 'chat_Bob' });

この状況の結果は、1件の通知となります。2番目の通知が、同じタグを持つ最初の通知を置き換えます。通知をキューに入れる(先入れ先出し)プラットフォームでは、タグを用いることで、通知のキュー内の位置を維持することもできます。最新の通知が最初に提示されるプラットフォームの場合は、close()メソッドを用いると同様の結果を得ることができます。

参考文献

[BIDI]
Unicode Bidirectional Algorithm, Mark Davis. Unicode Consortium.
[DOM4]
DOM, Anne van Kesteren, Aryeh Gregor, Ms2ger et al.. W3C.
[HTML5]
HTML5, Robin Berjon, Steve Faulkner, Travis Leithead et al.. W3C.
[LANG]
Tags for Identifying Languages; Matching of Language Tags, Addison Phillips and Mark Davis. IETF.
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels, Scott Bradner. IETF.
[URL]
URL, Eric Arvidsson, Michael[tm] Smith. W3C.
[WEBIDL]
Web IDL, Cameron McCormack. W3C.

謝辞

Aharon (Vladimir) Lanin、Alex Russell、David Håsäther、Doug Turner、Drew Wilson、Jake Archibald、Edward O'Connor、Frederick Hirsch、Ian Hickson、James Graham、Jon Lee、Jonas Sicking、Josh Soref、Michael Cooper、Michael Henretty、Olli Pettay、Simon Pietersの素晴らしさに謝意を表します。WHATWGの通知API標準に関する継続的な作業に関してAnne van Kesterenに特別な感謝を申し上げます。