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

Pete LePage

Alexey Rodionov

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

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

注意： 這些應用程式不僅限於原生 Android 應用程式或通用 Windows 平台 (UWP) 應用程式，也可以是使用 Bubblewrap 和 PWABuilder 封裝的 PWA。

Bubblewrap 是一組開放原始碼程式庫，也是 Node.js 的指令列工具 (CLI)。Bubblewrap 由 Google Chrome 團隊開發，可協助開發人員產生、建構及簽署 Android 專案，以受信任的網路活動 (TWA) 啟動 PWA。

PWABuilder 是 Microsoft 開發的開放原始碼專案，開發人員只要輸入 PWA 的網址、輸入/編輯應用程式的中繼資料，然後按一下「產生」按鈕，即可封裝及簽署 PWA，並發布至 Microsoft Store、Google Play 商店、App Store 和 Meta Quest Store 等各種商店。

PWABuilder 會在幕後使用 Bubblewrap，封裝適用於 Android 和 ChromeOS 的 PWA。

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

例如：

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

什麼是「取得已安裝的相關應用程式」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： Chrome 80 以上版本
通用 Windows 平台 (UWP) 應用程式	僅限 Windows： Chrome 85 以上版本 Edge 85 以上版本
在相同來源的相同範圍內安裝漸進式網頁應用程式 (PWA)	Android： Chrome 84 以上版本電腦 (Windows、macOS、Linux、ChromeOS)： Chrome 140 以上版本 Edge 140 以上版本
在相同或不同來源的不同範圍中安裝漸進式網頁應用程式 (PWA)	僅限 Android： Chrome 84 以上版本

確認是否已安裝 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>

專家級提示：這是陣列。也就是說，您可以在 Android 應用程式和多個網站之間定義已驗證的關係。

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

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

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

platform 必須為 play
id 是 Android 套件 ID

{
  ...
  "related_applications": [
    {
      "platform": "play",
      "id": "com.example.twa"
    }
  ]
  ...
}

專家級提示：這是陣列。也就是說，您可以定義網站與多個 Android 應用程式之間的已驗證關係。

確認應用程式是否已安裝

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

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

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

支援的裝置：

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

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

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

在應用程式的資訊清單檔案 AppxManifest.xml 或 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 命名空間。

如果網站有多個地址，請在 <uap3:AppUriHandler> 中為每個地址新增個別的 <uap3:Host Name=... /> 項目。

接著，建立名為 windows-app-web-link 的 JSON 檔案 (不含 .json 副檔名)，並提供應用程式的套件系列名稱。將該檔案放在 /.well-known/ 目錄或伺服器根目錄中。

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

專家級提示：這是陣列。也就是說，您可以為網站和多個 Windows 應用程式定義已驗證的關係。

如要找出可安裝應用程式的套件系列名稱，請在 PowerShell 中執行下列指令，並在清單中找出您的應用程式：

Get-AppxPackage | Select-Object PackageFamilyName

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

向網站說明 Windows 應用程式

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

platform 必須為 windows
id 是應用程式的套件系列名稱，結尾附加 !App 做為後置字元

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

專家級提示：這是陣列。也就是說，您可以為網站和多個 Windows 應用程式定義已驗證的關係。

確認應用程式是否已安裝

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

請參閱這個範例。

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

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

支援的裝置：

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 所在的網域 /.well-known/ 目錄中新增 assetlinks.json 檔案，例如 app.example.com。在 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

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

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

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

專家級提示：這是陣列。也就是說，您可以定義網站與多個 PWA 之間的已驗證關係。

檢查 PWA 是否已安裝

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

還有問題嗎？

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

意見回饋

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

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

實用連結

謝謝

特別感謝 Microsoft 的 Sunggook Chue 協助測試 Windows 應用程式的詳細資料，以及 Rayan Kanso 協助處理 Chrome 詳細資料。

應用程式是否已安裝？「取得已安裝的相關應用程式」API 會告訴您！ 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

什麼是「取得已安裝的相關應用程式」API？

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

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

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

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

確認應用程式是否已安裝

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

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

向網站說明 Windows 應用程式

確認應用程式是否已安裝

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

讓 PWA 瞭解自己

檢查 PWA 是否已安裝

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

向 PWA 說明您的網站

向網站說明您的 PWA

檢查 PWA 是否已安裝

還有問題嗎？

意見回饋

實用連結

謝謝

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