應用程式是否已安裝？「取得已安裝的相關應用程式」API 會告訴您！

Pete LePage

Alexey Rodionov

Get Installed Related Apps API 可取得已安裝相關應用程式的清單，以及相關詳細資料。

您可以使用這項功能，從漸進式網頁應用程式 (PWA) 本身和相關網頁 (例如產品行銷網站)，檢查目前裝置是否已安裝漸進式網頁應用程式、Android 應用程式或通用 Windows 平台 (UWP) 應用程式。

如果已安裝應用程式，您可以自訂使用者體驗。

例如：

• 如果其他應用程式已安裝，則不會宣傳 PWA 的安裝。
• 將使用者從產品行銷網站直接重新導向至應用程式。
• 將通知等部分功能集中在其他應用程式中，避免重複通知。

什麼是 Get Installed Related Apps API？

呼叫非同步 navigator.getInstalledRelatedApps() 方法會傳回 Promise，並以物件陣列解析，其中包含下列應用程式的詳細資料：

• 安裝在目前裝置上，
• 在網頁應用程式資訊清單的 related_applications 欄位中定義，
• 與呼叫 navigator.getInstalledRelatedApps() 方法的網頁有已驗證的關係 (詳情請參閱下節)。

const installedRelatedApps = await navigator.getInstalledRelatedApps?.();

呼叫 console.log(installedRelatedApps) 會傳回類似下列內容：

[
  {
    platform: "webapp",
    id: "https://example.com/?utm_source=home_screen",
    url: "https://example.com/manifest.json"
  },
  {
    platform: "play",
    id: "com.example.twa",
    url: "https://play.google.com/store/apps/details?id=com.example.twa",
    version: "0.1.0"
  }
]

舉例來說，如要檢查使用者的裝置是否已安裝任何相關應用程式，可以使用下列單行程式碼：

const hasInstalledRelatedApps = !!(await navigator.getInstalledRelatedApps?.())?.length;

如果您知道套件 ID，可以使用下列單行指令取得已安裝相關 Android 應用程式的版本號碼：

const installedRelatedAndroidAppVersion = (await navigator.getInstalledRelatedApps?.())?.find(app => app.id === 'com.example.twa')?.version;

可查看的支援應用程式類型

確認是否已安裝 Android 應用程式

網站可以檢查是否已安裝 Android 應用程式。

支援的裝置：

• 僅限 Android：Chrome 80 以上版本

向 Android 應用程式說明您的網站

首先，您需要更新 Android 應用程式，使用 Digital Asset Links 系統定義網站與 Android 應用程式之間的關係。這樣可確保只有您的網站可以檢查 Android 應用程式是否已安裝。

在 Android 應用程式的 AndroidManifest.xml 中，新增 asset_statements 項目：

<manifest>
  <application>
   …
    <meta-data android:name="asset_statements" android:resource="@string/asset_statements" />
   …
  </application>
</manifest>

接著，在 strings.xml 中新增下列資產陳述式，並將 site 更新為您的網域。請務必加入逸出字元。

<string name="asset_statements">
  [{
    \"relation\": [\"delegate_permission/common.handle_all_urls\"],
    \"target\": {
      \"namespace\": \"web\",
      \"site\": \"https://example.com\"
    }
  }]
</string>

完成後，請在裝置上安裝更新後的應用程式，或發布至 Google Play 商店或其他 Android 應用程式發布平台。

向網站說明您的 Android 應用程式

接著，請在網頁中加入網頁應用程式資訊清單，向網站說明您的 Android 應用程式。資訊清單必須包含 related_applications 屬性，這個陣列會提供應用程式的詳細資料，包括 platform 和 id。

• platform 必須為 play
• id 是 Android 套件 ID

{
  "related_applications": [{
    "platform": "play",
    "id": "com.android.chrome"
  }]
}

確認應用程式是否已安裝

最後，呼叫非同步函式 navigator.getInstalledRelatedApps()，檢查是否已安裝 Android 應用程式。

檢查是否已安裝 Windows (UWP) 應用程式

網站可以檢查您是否已安裝 Windows 應用程式 (使用 UWP 建構)。

支援的裝置：

• 僅限 Windows：Chrome 85 以上版本、Edge 85 以上版本

向 Windows 應用程式說明您的網站

您必須更新 Windows 應用程式，使用 URI 處理常式定義網站與 Windows 應用程式之間的關係。這項設定可確保只有您的網站能檢查 Windows 應用程式是否已安裝。

在應用程式的資訊清單檔案 Package.appxmanifest 中，新增 Windows.appUriHandler 擴充功能註冊。舉例來說，如果網站的地址是 example.com，您會在應用程式的資訊清單中新增下列項目：

<Applications>
  <Application Id="App" ... >
      ...
      <Extensions>
         <uap3:Extension Category="windows.appUriHandler">
          <uap3:AppUriHandler>
            <uap3:Host Name="example.com" />
          </uap3:AppUriHandler>
        </uap3:Extension>
      </Extensions>
  </Application>
</Applications>

請注意，您可能需要在 <Package> 屬性中加入 uap3 命名空間。

接著，建立名為 windows-app-web-link 的 JSON 檔案 (不含 .json 副檔名)，並提供應用程式的套件系列名稱。將該檔案放在伺服器根目錄或 /.well-known/ 目錄中。您可以在應用程式資訊清單設計工具的「封裝」部分中找到套件系列名稱。

[{
  "packageFamilyName": "MyApp_9jmtgj1pbbz6e",
  "paths": [ "*" ]
}]

如要瞭解如何設定 URI 處理常式，請參閱「使用應用程式 URI 處理常式為網站啟用應用程式」。

向網站說明 Windows 應用程式

接著，請在網頁中新增網頁應用程式資訊清單，向網站說明您的 Windows 應用程式。資訊清單必須包含 related_applications 屬性，這個陣列會提供應用程式的詳細資料，包括 platform 和 id。

• platform 必須為 windows
• id 是應用程式的套件系列名稱，後面附加 Package.appxmanifest 檔案中的 <Application> Id 值。

{
  "related_applications": [{
    "platform": "windows",
    "id": "MyApp_9jmtgj1pbbz6e!App"
  }]
}

確認應用程式是否已安裝

最後，呼叫非同步函式 navigator.getInstalledRelatedApps()，檢查是否已安裝 Windows 應用程式。

請參閱這個範例。

檢查是否已安裝漸進式網頁應用程式 (在範圍內)

PWA 可以檢查是否已安裝。在這種情況下，提出要求的網頁必須位於相同網域，且在 PWA 的範圍內 (如網頁應用程式資訊清單中的範圍所定義)。

支援的裝置：

• Android：Chrome 84 以上版本
• 桌機 (Windows、macOS、Linux、ChromeOS)：Chrome 140 以上版本、Edge 140 以上版本

讓 PWA 瞭解自己

在 PWA 的網頁應用程式資訊清單中新增 related_applications 項目，向 PWA 說明自身。

• platform 必須為 webapp
• url 是 PWA 網頁應用程式資訊清單的路徑 (可以是相對路徑)
• id 是在網頁應用程式資訊清單的 id 欄位中宣告，或由瀏覽器計算的網頁應用程式 ID (電腦版需要，Android 版不需要)

{
  …
  "scope": "/",
  "start_url": "/?utm_source=home_screen",
  "related_applications": [{
    "platform": "webapp",
    "url": "/manifest.json",
    "id": "https://example.com/?utm_source=home_screen"
  }],
  …
}

檢查 PWA 是否已安裝

最後，從 PWA 的範圍內呼叫非同步函式 navigator.getInstalledRelatedApps()，檢查是否已安裝。如果 navigator.getInstalledRelatedApps() 是在 PWA 範圍外呼叫，則會傳回 []。詳情請參閱下節。

檢查是否已安裝漸進式網頁應用程式 (不在範圍內)

即使網頁位於 PWA 的範圍外，您的網站仍可檢查 PWA 是否已安裝。舉例來說，從 /landing/ 放送的到達網頁可以檢查從 /pwa/ 放送的 PWA 是否已安裝，或是您的到達網頁從 www.example.com 放送，而 PWA 從 app.example.com 放送。

支援的裝置：

• 僅限 Android：Chrome 84 以上版本

向 PWA 說明您的網站

首先，您必須將數位資產連結新增至 PWA 服務的伺服器。這有助於定義網站與 PWA 之間的關係，並驗證只有您的網站可以檢查 PWA 是否已安裝。

在 PWA 所在的網域 (例如 app.example.com) 的 /.well-known/ 目錄中新增 assetlinks.json 檔案。在 site 屬性中，提供將執行檢查的網頁應用程式資訊清單完整路徑 (不是 PWA 的網頁應用程式資訊清單)。

// Served from https://app.example.com/.well-known/assetlinks.json
[
  {
    "relation": ["delegate_permission/common.query_webapk"],
    "target": {
      "namespace": "web",
      "site": "https://www.example.com/manifest.json"
    }
  }
]

向網站說明您的 PWA

接著，請在網頁中新增網頁應用程式資訊清單，向網站說明您的 PWA 應用程式。資訊清單必須包含 related_applications 屬性，這個陣列會提供 PWA 的詳細資料，包括 platform 和 url。

• platform 必須為 webapp
• url 是 PWA 網頁應用程式資訊清單的完整路徑

{
  "related_applications": [{
    "platform": "webapp",
    "url": "https://app.example.com/manifest.json"
  }]
}

檢查 PWA 是否已安裝

最後，呼叫非同步函式 navigator.getInstalledRelatedApps()，檢查 PWA 是否已安裝。

還有問題嗎？

如果還有疑問，查看 StackOverflow 上的 getInstalledRelatedApps 標記，看看是否有其他人提出類似問題。如果沒有，請在該處提問，並務必加上 progressive-web-apps 標記。我們的團隊會經常監控該標記，並盡量回答您的問題。

意見回饋

您是否發現 Chrome 實作方式有錯誤？或者實作方式與規格不同？

• 前往 https://new.crbug.com 提出錯誤回報。請盡可能詳述所有細節，提供重現錯誤的操作說明，並在「Components」(元件) 方塊中輸入 Mobile>WebAPKs。

實用連結

• Get Installed Related Apps API 公開說明
• 規格草案
• 追蹤錯誤
• ChromeStatus.com 項目
• Blink 元件：Mobile>WebAPKs

謝謝

特別感謝 Microsoft 的 Sunggook Chue 提供 Windows 應用程式測試的詳細資訊，以及 Rayan Kanso 提供 Chrome 詳細資訊。