Navigator: getInstalledRelatedApps() メソッド

Experimental: これは実験的な機能です。
本番で使用する前にブラウザー互換性一覧表をチェックしてください。

安全なコンテキスト用: この機能は一部またはすべての対応しているブラウザーにおいて、安全なコンテキスト (HTTPS) でのみ利用できます。

getInstalledRelatedApps() メソッドは、ユーザーがインストールしたプラットフォーム専用のアプリやプログレッシブウェブアプリを表すオブジェクトの配列で解決するプロミスを返します。プラットフォーム専用のアプリや PWA がすでにインストールされている場合、ウェブアプリから「アプリをインストール」のバナーが除去されるなど、コンテンツの個人設定に使用することができます。

メモ: このメソッドは、最上位の安全なコンテキストから呼び出す必要があります。つまり、<iframe> に埋め込まれたところからは呼び出せません。

解説

getInstalledRelatedApps() を使用すると、このメソッドを呼び出しているウェブアプリに関連するユニバーサル Windows プラットフォーム (UWP) アプリ、Android アプリ、PWA のインストール状況を調べることができます。

呼び出しているウェブアプリをプラットフォーム専用のアプリまたは PWA と関連付けるには、次の 2 つのことを行う必要があります。

  1. 呼び出すウェブアプリは、マニフェストファイル の related_applications メンバーで指定する必要があります。
  2. プラットフォーム専用のアプリまたは PWA は、呼び出し元のアプリとの関係を定義する必要があります。

関係を定義する方法は、アプリの機種によって異なります。

  • Android アプリは、デジタル資産リンクシステムを介して行います。
  • Windows UWP アプリは、URI ハンドラーを介して行います。
  • PWA は、次のような方法で行います。
    • PWA の場合、related_applications マニフェストメンバー内に自分自身で定義した項目で、基盤となるプラットフォームにインストールされているかどうかを調べます。
    • PWA 以外のアプリの場合、/.well-known/ ディレクトリーにある assetlinks.json ファイルに、インストールされているかどうかを調べるコードを記述します。

これらのケースのそれぞれを処理する方法の詳細については、Is your app installed? getInstalledRelatedApps() will tell you! を参照してください。

メモ: ほとんどの対応ブラウザーでは、インストール可能な PWA が検出された場合、独自のインストール UI を指定しています。これは、すでにインストールされている場合は表示されません。詳しくは、PWA をインストール可能にする > ウェブからのインストールを参照してください。この表示は、beforeinstallprompt イベントを使用して抑制することができます。また、getInstalledRelatedApps() と組み合わせて、プラットフォーム専用のアプリが利用できるかどうかによって表示を抑制することもできます。詳しくは、Trigger installation from your PWAを参照してください。

構文

js
getInstalledRelatedApps()

引数

なし。

返値

Promise で、インストールされた相対アプリを表すオブジェクトの配列で履行されます。各オブジェクトは、以下のプロパティを含むことができます。

id 省略可

指定されたプラットフォーム上でアプリケーションを表すために使用する ID を表す文字列。文字列の正確な書式はプラットフォームによって異なります。

platform

関連するアプリが関連付けられているプラットフォーム（エコシステムまたはオペレーティングシステム）を表す文字列です。 以下のいずれかになります。

url 省略可

アプリに関連付けられた URL を表す文字列です。通常、この場所でアプリに関する情報を読み、インストールすることができます。

version 省略可

関連するアプリのバージョンを表す文字列です。

関連するアプリの情報は、前回呼び出したウェブアプリの マニフェストファイル のメンバーである related_applications に指定された情報である必要があります。

例外

InvalidStateError DOMException

このメソッドが、最上位の閲覧コンテキストで呼び出されませんでした。

例

js
const relatedApps = await navigator.getInstalledRelatedApps();

// 関連のアプリをすべてコンソール内の表に書き出す
console.table(relatedApps);

// プラットフォーム専用の特定のアプリを検索
const psApp = relatedApps.find((app) => app.id === "com.example.myapp");

if (psApp && doesVersionSendPushMessages(psApp.version)) {
  // プッシュ通知の送信を処理するプラットフォーム専用のアプリがインストールされている
  // ウェブアプリで処理する必要はない
  return;
}

メモ: この例では、doesVersionSendPushMessages() は理論上の開発者定義関数であり、ブラウザーによって提供されているわけではありません。

仕様書

Specification
Get Installed Related Apps API
# dom-navigator-getinstalledrelatedapps

ブラウザーの互換性

BCD tables only load in the browser

関連情報