已安裝您的應用程式嗎?getInstalledRelatedApps() 就會告訴你!

getInstalledRelatedApps() 方法可讓網站檢查使用者的裝置是否已安裝 iOS/Android/電腦版應用程式或 PWA。

什麼是 getInstalledRelatedApps() API?

使用 getInstalledRelatedApps() 判斷是否已安裝 Android 應用程式的網站。

getInstalledRelatedApps() 可讓「您的」頁面檢查「您的」行動版或電腦版應用程式,在某些情況下,也可以檢查使用者裝置是否已安裝漸進式網頁應用程式 (PWA),並能在使用者的裝置上自訂使用者體驗。

舉例來說,假如使用者已安裝您的應用程式:

  • 將使用者從產品行銷頁面直接重新導向至您的應用程式。
  • 集中將某些功能 (例如通知) 在其他應用程式中,防止重複通知。
  • 如果已安裝其他應用程式,則不宣傳 PWA 安裝程序

如要使用 getInstalledRelatedApps() API,您需要向應用程式提供網站相關資訊,並將應用程式相關資訊告知網站。一旦您定義兩者之間的關係,您就可以檢查應用程式是否已安裝。

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

應用程式類型 可檢查日期
Android 應用程式 僅限 Android 裝置
Chrome 80 以上版本
Windows (UWP) 應用程式 僅限 Windows
Chrome 85 以上版本
Edge 85 以上版本
漸進式網頁應用程式
安裝在相同範圍不同範圍中。
僅限 Android 裝置
Chrome 84 以上版本

檢查是否已安裝 Android 應用程式

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

支援來源

Android:Chrome 80 以上版本

向 Android 應用程式提供網站相關資訊

首先,您必須使用 Digital Asset Links 系統更新 Android 應用程式,以定義網站和 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 應用程式發布到 Play 商店。

為您的網站提供 Android 應用程式相關資訊

接下來,請在網頁中新增網頁應用程式資訊清單,向您的網站提供 Android 應用程式的相關資訊。資訊清單必須包含 related_applications 屬性,此陣列可提供應用程式的詳細資料,包括 platformid

  • platform 必須是 play
  • id 是您 Android 應用程式的 Google Play 應用程式 ID
{
  "related_applications": [{
    "platform": "play",
    "id": "com.android.chrome",
  }]
}

檢查是否已安裝應用程式

最後,呼叫 navigator.getInstalledRelatedApps() 檢查是否已安裝您的 Android 應用程式。

試用示範

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

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

支援來源

Windows:Chrome 85 以上版本、Edge 85 以上版本

將您的網站告知 Windows 應用程式

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

Windows.appUriHandler 擴充功能註冊新增至應用程式的資訊清單檔案 Package.appxmanifest。舉例來說,如果網站網址是 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>

請注意,您可能需要將 uap3 命名空間新增至 <Package> 屬性。

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

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

如需設定 URI 處理常式的完整詳細資料,請參閱使用應用程式 URI 處理常式啟用網站的應用程式

將 Windows 應用程式告知網站

接下來,請在網頁中新增網頁應用程式資訊清單,向網站提供 Windows 應用程式的相關資訊。資訊清單必須包含 related_applications 屬性,此陣列可提供應用程式的詳細資料,包括 platformid

  • platform 必須是 windows
  • id 是應用程式的套件名稱系列名稱,後面加上 Package.appxmanifest 檔案中的 <Application> Id 值。
{
  "related_applications": [{
    "platform": "windows",
    "id": "MyApp_9jmtgj1pbbz6e!App",
  }]
}

檢查是否已安裝應用程式

最後,呼叫 navigator.getInstalledRelatedApps() 檢查是否已安裝 Windows 應用程式。

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

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

支援來源

Android:Chrome 84 以上版本

向 PWA 自我介紹

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

  • platform 必須是 webapp
  • url 是 PWA 網頁應用程式資訊清單的完整路徑
{
  …
  "scope": "/",
  "start_url": "/",
  "related_applications": [{
    "platform": "webapp",
    "url": "https://example.com/manifest.json",
  }],
  …
}

檢查是否已安裝 PWA

最後,從 PWA 的範圍內呼叫 navigator.getInstalledRelatedApps(),檢查是否已安裝。如果呼叫 getInstalledRelatedApps() 的範圍不在 PWA 的範圍之內,則會傳回 false。詳情請參閱下節。

試用示範

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

網站可以檢查是否已安裝 PWA,即使網頁不在 PWA 的範圍內也一樣。舉例來說,從 /landing/ 提供的到達網頁可以檢查是否已安裝透過 /pwa/ 提供的 PWA,或者您的到達網頁是否透過 www.example.com 提供,而 PWA 是否來自 app.example.com

支援來源

Android:Chrome 84 以上版本

向 PWA 說明您的網站

首先,您需要將數位資產連結新增至提供 PWA 的伺服器。這有助於定義網站和 PWA 的關係,確保只有你的網站才能檢查 PWA 是否已安裝。

assetlinks.json 檔案新增至 PWA 所在網域的 /.well-known/ 目錄,例如 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 應用程式的相關資訊。資訊清單必須包含 related_applications 屬性,此陣列可提供 PWA 的相關詳細資料,包括 platformurl

  • platform 必須是 webapp
  • url 是 PWA 網頁應用程式資訊清單的完整路徑
{
  "related_applications": [{
    "platform": "webapp",
    "url": "https://app.example.com/manifest.json",
  }]
}

檢查是否已安裝 PWA

最後,呼叫 navigator.getInstalledRelatedApps() 以檢查 PWA 是否已安裝。

試用示範

呼叫 getInstalledRelatedApps()

呼叫 navigator.getInstalledRelatedApps() 會傳回承諾,此陣列可解析在使用者裝置上安裝的應用程式。

const relatedApps = await navigator.getInstalledRelatedApps();
relatedApps.forEach((app) => {
  console.log(app.id, app.platform, app.url);
});

為避免網站測試的所有應用程式組合過於廣泛,系統只會將網頁應用程式資訊清單中宣告的前三個應用程式納入考量。

如同大多數其他強大的網路 API,getInstalledRelatedApps() API 只有在透過 HTTPS 提供時才能使用。

還有其他疑問嗎?

還有其他問題嗎?檢查 StackOverflow 上的 getInstalledRelatedApps 標記,瞭解是否有人提出類似問題。如果沒有,請詢問您的問題,並務必加上 progressive-web-apps 標記。我們的團隊會經常監控該標記,並嘗試回答您的問題。

意見回饋:

您在執行 Chrome 時發現錯誤了嗎?還是實作與規格不同?

  • 前往 https://new.crbug.com 回報錯誤。請盡可能加入詳細資料,提供重現錯誤的簡易操作說明,然後在「Components」方塊中輸入 Mobile>WebAPKsGlitch 適合用來快速分享簡單快速的作品。

展現對 API 的支援

您打算使用 getInstalledRelatedApps() API 嗎?您的公開支援可協助 Chrome 團隊決定功能的優先順序,讓其他瀏覽器廠商瞭解這些功能對他們的支援程度有多重要。

實用連結

感謝

特別感謝 Microsoft 的 Sunggook Chue 提供詳細的測試 Windows 應用程式說明,Rayan Kanso 則會提供 Chrome 詳細資料的協助。