Web App Launch Handler API

この仕様は、すでに開いているアプリインスタンスに関して、Web アプリケーションがアプリ起動の挙動を構成できるようにする API を定義する。この API は、音楽プレイヤーなどの単一インスタンス Web アプリのニーズに応えることを目的としている。

使用例

音楽プレイヤーアプリは、音楽の再生を中断することなく、アプリショートカットによる起動を既存のウィンドウへ送ることを望む。この音楽アプリは、次に示すように [[[appmanifest]]] に [=manifest/launch_handler=] エントリを追加することになる。

      {
        "name": "Music Player",
        "shortcuts": [{
          "name": "Now Playing",
          "url": "/"
        }, {
          "name": "Library",
          "url": "/library"
        }, {
          "name": "Favorites",
          "url": "/favorites"
        }, {
          "name": "Discover",
          "url": "/discover"
        }],
        "launch_handler": {
          "client_mode": "focus-existing"
        }
      }

[=manifest/client_mode=] パラメーターを [=client mode/focus-existing=] に設定すると、アプリ起動は、既存のアプリインスタンス（存在する場合）を、現在の文書からナビゲートさせることなくフォーカスする。

{{LaunchParams}} は、音楽プレイヤーがその {{LaunchConsumer}} 内で {{LaunchParams/targetURL}} を読み取り、スクリプトで処理できるように、{{Window/launchQueue}} にキュー投入される。例：

        window.launchQueue.setConsumer((launchParams) => {
          const url = launchParams.targetURL;
          // If the URL is to one of the app sections, updates the app view to
          // that section without interrupting currently playing music.
          if (maybeFocusAppSection(url)) {
            return;
          }
          // Could not handle the launch in-place, just navigate the page
          // (interrupts any playing music).
          location.href = url;
        });

すでに音楽プレイヤーアプリを使って音楽を聴いているユーザーが、 "Library" アプリショートカットを起動すると、/library へのアプリ起動がトリガーされる。この起動は既存のアプリインスタンスへルーティングされ、ページの {{Window/launchQueue}} にキュー投入される。そして、割り当てられた {{LaunchConsumer}} を通じて、現在の音楽再生に影響を与えることなく、音楽プレイヤーのライブラリセクションをフォーカスする。

Web App Manifest への拡張

次の手順は、拡張ポイント、すなわち manifest を処理する手順に追加される。

[=ordered map=] |json:ordered map| と [=ordered map=] |manifest:ordered map| を与えて、[=processing the launch_handler member=] の手順を実行する。

[=manifest/launch_handler=] メンバー

`launch_handler` は、 Web アプリ起動がどのように挙動すべきかの構成を含む辞書である。

[=manifest/client_mode=] が唯一のメンバーであるにもかかわらず、 [=manifest/launch_handler=] は辞書である。これは、将来ほかの種類の挙動が必要になった場合に、さらにメンバーを追加できる余地を与えるためである。

[=ordered map=] |json:ordered map|、[=ordered map=] |manifest:ordered map| が与えられたときの、 processing the launch_handler member の手順は次のとおりである。

|json|["launch_handler"] が [=map/exist=] しない場合は、戻る。
|json|["launch_handler"] の型が [=ordered map=] でない場合は、戻る。
|manifest|["launch_handler"] を新しい [=ordered map=] に設定する。
|json|["launch_handler"], |manifest|["launch_handler"] を渡して [=Process the `client_mode` member=]。

[=manifest/client_mode=] メンバー

[=manifest/launch_handler=] の `client_mode` メンバーは、 1 つ以上の [=client mode targets=] を指定する [=string=] または [=strings=] のリストである。[=client mode target=] は、 Web アプリ起動に使用する特定のクライアント選択およびナビゲーション挙動を宣言する。

ユーザーエージェントは、プラットフォームの制約に応じて、 [=client mode targets=] のサブセットのみをサポートしてもよい（例：モバイルデバイスは、複数のアプリインスタンスを同時にサポートしない場合がある）。

client mode targets は次のとおりである。

auto: ユーザーエージェントの既定の起動ルーティング挙動が使用される。
ユーザーエージェントは、プラットフォームに最も適したものを決定することが期待される。たとえば、単一のアプリインスタンスのみをサポートするモバイルデバイスでは、ユーザーエージェントは `navigate-existing` を使用してもよい。一方、複数のウィンドウをサポートするデスクトップデバイスでは、データ損失を避けるために `navigate-new` を使用してもよい。
navigate-new: 起動のターゲット URL を読み込むために、新しい Web アプリクライアントが作成される。
navigate-existing: 既存の Web アプリクライアントが開いている場合、それはフォーカスされ、起動のターゲット URL へナビゲートされる。既存の Web アプリクライアントがない場合は、代わりに [=client mode/navigate-new=] 挙動が使用される。
focus-existing: 既存の Web アプリクライアントが開いている場合、それはフォーカスされるが、起動のターゲット URL へはナビゲートされない。代わりに、ターゲット URL は {{LaunchParams}} を介して伝達される。既存の Web アプリクライアントがない場合は、代わりに [=client mode/navigate-new=] 挙動が使用される。
起動の {{LaunchParams}} を受け取り、それに対して何かを行うには、ページが {{Window/launchQueue}} に {{LaunchConsumer}} を設定しておく必要がある。ページが何も処理しない場合、起動のユーザー体験は壊れているように見える可能性が高い。

[=ordered map=] |json_launch_handler:ordered map|、 [=ordered map=] |manifest_launch_handler:ordered map| が与えられたとき、 process the `client_mode` member するには、次を実行する。

|json_launch_handler|["client_mode"] が [=map/exist=] しない場合は、戻る。
|json_launch_handler|["client_mode"] の型が [=list=] の場合：
1. |json_launch_handler|["client_mode"] の |entry| それぞれについて [=list/For each=]：
  1. |entry| の型が [=string=] でない場合は、続行する。
  2. |entry| がユーザーエージェントによってサポートされている場合、 |manifest_launch_handler|["client_mode"] を |entry| に設定して戻る。
|json_launch_handler|["client_mode"] が [=string=] であり、ユーザーエージェントによってサポートされている場合、 |manifest_launch_handler|["client_mode"] を |json_launch_handler|["client_mode"] に設定して戻る。
|manifest_launch_handler|["client_mode"] を [=client mode/auto=] に設定する。

`client_mode` は文字列のリストを受け入れる。これによりサイトは、推奨する [=client mode target=] がユーザーエージェントまたはプラットフォームでサポートされていない場合に使用する、フォールバックの [=client mode targets=] を指定できる。リスト内で最初にサポートされている [=client mode target=] エントリが使用される。

Web アプリ起動の処理

処理付きで Web アプリを起動する

この仕様は、[=manifest/launch_handler=] の挙動を含めるため、既存の [=launch a web application=] アルゴリズムを、 [=launch a web application with handling=] の手順に置き換える。

launch a web application with handling する手順は、次のアルゴリズムで与えられる。このアルゴリズムは、 [=Document/processed manifest=] |manifest:processed manifest|、任意の [=URL=] または {{LaunchParams}} |params|、任意の [=POST resource=] |POST resource| を取り、 [=application context=] を返す。

|params| が与えられていない場合、|params| を |manifest|.[=manifest/start_url=] に設定する。
|params| が [=URL=] の場合、{{LaunchParams/targetURL}} を |params| に設定した新しい {{LaunchParams}} に |params| を設定する。
Assert: |params|.{{LaunchParams/targetURL}} は |manifest| の [=manifest/within scope=] である。
|manifest|、|params|、|POST resource| を渡して [=prepare an application context=] する手順を実行した結果に、 |application context| を設定する。
|params| を、|application context| の文書の {{Window/launchQueue}} の [=unconsumed launch params=] に追加する。
|application context| の [=navigable/active document=] の {{Window/launchQueue}} に対して、[=process unconsumed launch params=] する手順を実行する。
|application context| は [=assigned launch consumer=] を持つ既存のインスタンスである可能性があるため、新たに追加された {{LaunchParams}} を処理する必要がある。

prepare an application context する手順は、次のアルゴリズムで与えられる。このアルゴリズムは、 [=Document/processed manifest=] |manifest:processed manifest|、 {{LaunchParams}} |launch params|、任意の [=POST resource=] |POST resource| を取り、[=application context=] を返す。

[=client mode target=] |client_mode| を |manifest|.[=manifest/launch_handler=].[=manifest/client_mode=] とする。
|client_mode| が [=client mode/auto=] の場合、ユーザーエージェントが最も適切であると判断したものに従い、|client_mode| を [=client mode/navigate-new=] または [=client mode/navigate-existing=] のいずれかに設定する。
|client mode| で分岐し、次の下位手順を実行する：
[=client mode/navigate-new=]
1. |manifest|、|launch params|.{{LaunchParams/targetURL}}、|POST resource| を渡して [=create a new application context=] する手順を実行した結果を返す。
[=client mode/navigate-existing=] または [=client mode/focus-existing=]
1. |manifest| が [=applied=] された [=application context=] が存在しない場合：
  1. |manifest|、 |launch params|.{{LaunchParams/targetURL}}、|POST resource| を渡して [=create a new application context=] する手順を実行した結果を返す。
2. |application context| を、|manifest| が [=applied=] された [=application context=] とする。複数ある場合は、ユーザーエージェントが最も適切なものを選択する。
  適切な選択戦略としては、最も最近フォーカスされていたものを選ぶことが考えられる。
3. |client mode| が [=client mode/focus-existing=] であり、 |application context| の現在のセッション履歴エントリの URL が |manifest| の [=manifest/within scope=] である場合：
  1. |application context| のビューポートをフォーカスする。
  2. |application context| を返す。
4. |POST resource| を渡して、|application context| を |launch params|.{{LaunchParams/targetURL}} へ [=Navigate=] する。
5. |application context| を返す。

[=unconsumed launch params=] の処理

{{LaunchQueue}} |queue| が与えられたときの process unconsumed launch params する手順は次のとおりである。

[=assigned launch consumer=] |consumer| が |queue| に設定されている場合：
1. |queue| の [=unconsumed launch params=] の |launch_params:LaunchParams| それぞれについて [=list/For each=]：
  1. |consumer| を |launch_params| で呼び出す。
2. |queue| の [=unconsumed launch params=] を空リストに設定する。

アプリ起動に対するスクリプトインターフェイス

LaunchParams インターフェイス

これは Manifest Incubations から変更なしで直接コピーされたものであり、この [=manifest/launch_handler=] 仕様が、その置き換え先になるべきである。
{{LaunchParams}} は辞書であるべきである。
{{LaunchParams/targetURL}} は nullable であるべきではない。
{{LaunchParams/files}} は任意であるべきである
{{LaunchParams/targetURL}} 以外のメンバーについては、起動の種類を示すために、undefined でないものは 1 つだけであるべきである。

          [Exposed=Window] interface LaunchParams {
            readonly attribute DOMString? targetURL;
            readonly attribute FrozenArray<FileSystemHandle> files;
          };

{{LaunchParams/targetURL}} は、アプリケーションの [=manifest/within scope=] でなければならない、起動の [=URL=] を表す。

{{LaunchParams/files}} 内のすべての |file handle:FileSystemHandle| について、 {{FileSystemPermissionDescriptor/mode}} を {{FileSystemPermissionMode/"readwrite"}} に設定してファイルシステム権限を照会した場合、{{PermissionState/"granted"}} を返さなければならない。

LaunchConsumer 関数

          callback LaunchConsumer = any (LaunchParams params);

LaunchQueue インターフェイス

          partial interface Window {
            readonly attribute LaunchQueue launchQueue;
          };

          [Exposed=Window] interface LaunchQueue {
            undefined setConsumer(LaunchConsumer consumer);
          };

{{LaunchQueue}} は、初期状態で空の {{LaunchParams}} の [=list=] である unconsumed launch params を持つ。

{{LaunchQueue}} は、初期状態で null である任意の {{LaunchConsumer}}、すなわち assigned launch consumer を持つ。

setConsumer メソッド

{{LaunchQueue/setConsumer(consumer)}} メソッド手順は次のとおりである。

[=assigned launch consumer=] を |consumer| に設定する。
[=process unconsumed launch params=] する手順を実行する。

{{LaunchParams}} は、起動イベントの発火とページスクリプトによるイベントリスナーの取り付けとの間の競合状態を避けるために、イベント経由ではなく {{LaunchQueue}} 経由で文書へ渡される。対照的に、{{LaunchQueue}} は、{{LaunchConsumer}} が設定されるまで、キュー投入されたすべての {{LaunchParams}} をバッファする。

前提条件

使用例