起動ハンドラー API

概念と使用方法

launch_handler フィールドをウェブアプリのマニフェストファイルに追加することで、アプリの起動時の動作を指定することができます。これには、 client_mode というサブフィールドがあり、アプリの起動方法と移動先を指定する文字列値が含まれています。例を示します。

"launch_handler": {
    "client_mode": "focus-existing"
}

指定しなかった場合、既定の client_mode 値は auto です。利用できる値は次のとおりです。

focus-existing

最後に操作したウェブアプリのウィンドウの閲覧コンテキストが、起動処理のために選択されます。 これにより、 window.launchQueue.setConsumer() のコールバック関数に渡される LaunchParams オブジェクトの targetURL プロパティに、ターゲットの起動URLが設定されます。 下記で説明するように、これによって、アプリの起動処理に独自の機能を設定することができます。

navigate-existing

ウェブアプリウィンドウで最後に操作した閲覧コンテキストが、ターゲットの起動 URL へ移動します。ターゲットの URL は、 window.launchQueue.setConsumer() を通じて引き続き利用できるため、追加のカスタム起動ナビゲーション処理を実装することができます。

navigate-new

ウェブアプリウィンドウに新しい閲覧コンテキストが作成され、ターゲットの起動 URL が読み込まれます。ターゲットの URL は、 window.launchQueue.setConsumer() を通じて引き続き利用できるため、追加のカスタム起動ナビゲーション処理を実装することができます。

auto

ユーザーエージェントは、プラットフォームに最適なものを決定します。例えば、単一のアプリインスタンスが一般的であるモバイルでは、 navigate-existing の方が意味がある可能性が高いですが、デスクトップのコンテキストでは、 navigate-new の方が意味がある可能性が高いでしょう。これは、指定された値が不正な場合に用いられる既定値です。

focus-existing を使用すると、 window.launchQueue.setConsumer() のコールバック関数の中でコードを記載して、 targetURL をカスタム処理して指定することができます。

window.launchQueue.setConsumer((launchParams) => {
  // Do something with launchParams.targetURL
});

インターフェイス

LaunchParams

PWA でカスタムの起動ナビゲーション処理を実装する際に使用します。 window.launchQueue.setConsumer() を呼び出して起動ナビゲーション処理機能を設定すると、 setConsumer() の中のコールバック関数で LaunchParams オブジェクトのインスタンスが渡されます。

LaunchQueue

プログレッシブウェブアプリ (PWA) が launch_handler の client_mode 値を focus-existing、navigate-new、navigate-existing で起動される場合、 LaunchQueue は PWA にカスタム起動ナビゲーション処理を実装できる機能にアクセスできるようにします。この機能は、 setConsumer() コールバック関数に渡される LaunchParams オブジェクトのプロパティによって制御されます。

他のインターフェイスへの拡張

Window.launchQueue

LaunchQueue クラスへのアクセスを提供し、 launch_handler マニフェストフィールドの client_mode 値で示されたコンテキストで処理することで、プログレッシブウェブアプリ (PWA) にカスタム起動ナビゲーション処理を実装することができるようにします。

例

if ("launchQueue" in window) {
  window.launchQueue.setConsumer((launchParams) => {
    if (launchParams.targetURL) {
      const params = new URL(launchParams.targetURL).searchParams;

      // 再生するトラックを受け取る音楽プレーヤーアプリを想定
      const track = params.get("track");
      if (track) {
        audio.src = track;
        title.textContent = new URL(track).pathname.substr(1);
        audio.play();
      }
    }
  });
}

このコードは PWA に含まれ、アプリが読み込まれた際に起動時に実行されます。 window.launchQueue.setConsumer() のコールバック関数は、 LaunchParams.targetURL から検索パラメーターを抽出し、 track パラメーターを探し出したら、それを使用して <audio> 要素の src を設定し、これが指す音声トラックを再生します。

動作する完全なコードについては、 Musicr 2.0 デモアプリを参照してください。

仕様書

ブラウザーの互換性

関連情報

• Launch Handler API: Control how your app is launched
• Musicr 2.0 デモアプリ