PWA 做為網址處理常式

讓已安裝的 PWA 處理網址，享有更完善的整合體驗。

Thomas Steiner

警告：PWA 做為網址處理常式是功能專案的一部分，且對實驗性 url_handlers 資訊清單成員的支援正在逐步淘汰。url_handlers 資訊清單成員將由新的 handle_links 資訊清單成員取代，後者正在標準化和實作中。請參閱 handle_links 說明。

什麼是網址處理常式 PWA？

假設你正在使用 macOS 上的「訊息」等即時通訊應用程式與朋友聊天，討論音樂。假設你們都在裝置上安裝了 music.example.com PWA。如果您想與好友分享喜愛的曲目，可以傳送 https://music.example.com/rick-astley/never-gonna-give-you-up 等深層連結給對方。由於這個連結相當長，music.example.com 的開發人員可能決定為每首曲目新增額外的短連結，例如 https://🎵.example.com/r-a/n-g-g-y-u。

PWA 做為網址處理常式，可讓 music.example.com 等應用程式自行註冊為網址處理常式，處理符合 https://music.example.com、https://*.music.example.com 或 https://🎵.example.com 等模式的網址，這樣一來，PWA 外部的連結 (例如即時通訊應用程式或電子郵件用戶端) 就會在已安裝的 PWA 中開啟，而不是在瀏覽器分頁中開啟。

PWA 做為網址處理常式包含兩個新增項目：

1. "url_handlers" 網頁應用程式資訊清單成員。
2. web-app-origin-association 檔案格式，用於驗證範圍內和範圍外的網址關聯。

PWA 做為網址處理常式的建議用途

可能使用這個 API 的網站包括：

• 音樂或影片串流網站，以便在應用程式的播放器中開啟曲目連結或播放清單連結。
• 新聞或 RSS 閱讀器，讓追蹤或訂閱的網站在應用程式的閱讀模式中開啟。

如何將 PWA 做為網址處理常式

透過 about://flags 啟用

如要在本機試用 PWA 做為網址處理常式，而不使用來源試用權杖，請在 about://flags 中啟用 #enable-desktop-pwas-url-handling 旗標。

注意：只有作業系統設定中的預設瀏覽器，才支援 PWA 做為網址處理常式的功能。舉例來說，您可以按照這些操作說明，將 Chrome 設為預設瀏覽器。

"url_handlers" 網頁應用程式資訊清單成員

如要將已安裝的 PWA 與網址模式建立關聯，必須在網頁應用程式資訊清單中指定這些模式。這項操作是透過 "url_handlers" 成員完成。這個函式接受具有 origin 屬性的物件陣列，該屬性是必要的 string，用於比對來源。這些模式可使用萬用字元 (*) 前置字元，以便納入多個子網域 (例如 https://*.example.com)。與這些來源相符的網址可由這個網頁應用程式處理。配置一律假設為 https://，但必須明確提及。

以下網頁應用程式資訊清單摘錄內容，說明簡介段落中的音樂 PWA 範例如何設定這項功能。第二個項目包含萬用字元 ("https://*.music.example.com")，可確保應用程式也會針對 https://www.music.example.com 或其他可能範例 (例如 https://marketing-activity.music.example.com) 啟用。

{
  "url_handlers": [
    {
      "origin": "https://music.example.com"
    },
    {
      "origin": "https://*.music.example.com"
    },
    {
      "origin": "https://🎵.example.com"
    }
  ]
}

注意：在線上情境中，https://🎵.example.com 的短連結通常會重新導向至 https://music.example.com。在離線情境下，這種導覽重新導向並非理想的替代方案。因此，應用程式需要註冊這兩個來源。

web-app-origin-association 檔案

由於 PWA 位於與其需要處理的部分網址 (例如 https://🎵.example.com) 不同的來源 (music.example.com)，因此應用程式需要驗證這些其他來源的擁有權。這會發生在其他來源託管的 web-app-origin-association 檔案中。

注意：如果應用程式要處理與 PWA 位於「相同」來源的網址，也必須在該來源託管的 web-app-origin-association 檔案中指定處理規則。

這個檔案必須包含有效的 JSON。頂層結構是物件，其中包含名為 "web_apps" 的成員。這個成員是物件陣列，每個物件代表一個不重複的網頁應用程式項目。每個物件包含：

欄位	說明	類型	預設
"manifest"	(必要) 相關 PWA 的網頁應用程式資訊清單網址字串	string	不適用
"details"	(選用) 包含納入和排除網址模式陣列的物件	object	不適用

每個 "details" 物件都包含：

欄位	說明	類型	預設
"paths"	(選用) 允許的路徑字串陣列	string[]	[]
"exclude_paths"	(選用) 不允許的路徑字串陣列	string[]	[]

以下是上述音樂 PWA 範例的 web-app-origin-association 檔案範例。這個檔案會託管在來源 🎵.example.com 上，並與 music.example.com PWA 建立關聯，由其網頁應用程式資訊清單網址識別。

{
  "web_apps": [
    {
      "manifest": "https://music.example.com/manifest.json",
      "details": {
        "paths": ["/*"],
        "exclude_paths": ["/internal/*"]
      }
    }
  ]
}

注意：web-app-origin-association 檔案類似於 Apple 的關聯網域檔案、Android 的 assetlinks.json 檔案和 Windows 的 windows-app-web-link 檔案。 不同之處在於，web-app-origin-association 檔案不會使用平台專屬應用程式 ID 參照 PWA，而是使用網頁應用程式資訊清單網址。

何時會比對出相符網址？

如果符合下列兩項條件，PWA 就會比對網址進行處理：

• 網址與 "url_handlers" 中的其中一個來源字串相符。
• 瀏覽器可以使用各自的 web-app-origin-association 檔案進行驗證，確認每個來源都同意讓這個應用程式處理這類網址。

關於 web-app-origin-association 檔案探索

為了讓瀏覽器找到 web-app-origin-association 檔案，開發人員必須將 web-app-origin-association 檔案放在應用程式根目錄的 /.well-known/ 資料夾中。檔案名稱必須完全符合 web-app-origin-association，才能正常運作。

示範

如要測試 PWA 做為網址處理常式，請務必按照所述設定瀏覽器旗標，然後在 https://mandymsft.github.io/pwa/ 安裝 PWA。查看其網頁應用程式資訊清單，您會發現它處理的網址模式如下：https://mandymsft.github.io 和 https://luhuangmsft.github.io。由於後者與 PWA 位於不同的來源 (luhuangmsft.github.io)，因此 mandymsft.github.io 上的 PWA 必須證明擁有權，這會使用託管於 https://luhuangmsft.github.io/.well-known/web-app-origin-association 的 web-app-origin-association 檔案進行。

如要測試是否確實有效，請使用您選擇的即時通訊應用程式，或在非網頁式電子郵件用戶端 (例如 macOS 上的郵件) 中查看電子郵件，向自己傳送測試訊息。電子郵件或簡訊應包含 https://mandymsft.github.io 或 https://luhuangmsft.github.io 連結。兩者都應在已安裝的 PWA 中開啟。

安全性和權限

Chromium 團隊根據「控管強大網路平台功能的存取權」中定義的核心原則 (包括使用者控制、透明度和人體工學)，設計並實作 PWA 做為網址處理常式。

使用者控制項

如果有多個 PWA 註冊為特定網址模式的網址處理常式，系統會提示使用者選擇要用哪個 PWA 處理該模式 (如果有的話)。本提案不處理從瀏覽器分頁開始的導覽，而是明確針對從瀏覽器外部開始的導覽。

透明度

如果 PWA 安裝期間因任何原因無法成功完成必要的關聯驗證，瀏覽器就不會將應用程式註冊為受影響網址的有效網址處理常式。如果網址處理常式導入不當，可能會遭人用來劫持網站流量。因此，應用程式關聯機制是這項配置的重要部分。

平台專屬應用程式已可使用作業系統 API，列舉使用者系統上安裝的應用程式。舉例來說，Windows 上的應用程式可以使用 FindAppUriHandlersAsync API 列舉網址處理常式。如果 PWA 在 Windows 中註冊為 OS 層級網址處理常式，其他應用程式就能看到 PWA。

權限保留

來源可隨時修改與 PWA 的關聯。瀏覽器會定期嘗試重新驗證已安裝網頁應用程式的關聯。如果網址處理常式註冊因關聯資料變更或不再可用而無法重新驗證，瀏覽器會移除註冊。

意見回饋

Chromium 團隊想瞭解您對 PWA 做為網址處理常式的使用體驗。

說明 API 設計

API 是否有任何部分無法如預期運作？還是缺少實作構想所需的方法或屬性？對安全性模型有任何疑問或意見嗎？在對應的 GitHub 存放區中回報規格問題，或在現有問題中加入您的想法。

回報導入問題

您是否發現 Chromium 實作有錯誤？還是實作方式與規格不同？請前往 new.crbug.com 回報錯誤。請務必盡可能提供詳細資訊和重現問題的操作說明，並在「Components」方塊中輸入 UI>Browser>WebAppInstalls。

表示對 API 的支持

您是否打算使用 PWA 做為網址處理常式？您的公開支持有助於 Chromium 團隊優先處理功能，並向其他瀏覽器供應商展示支援這些功能的重要性。

請使用主題標記 #URLHandlers 傳送推文至 @ChromiumDev，讓我們知道您在何處使用這項功能，以及使用方式。

實用連結

• 公開說明
• 示範 | 示範來源
• Chromium 追蹤錯誤
• ChromeStatus.com 項目
• Blink 元件：UI>Browser>WebAppInstalls
• TAG 審查
• Microsoft 說明文件

特別銘謝

「PWA 做為網址處理常式」是由 Microsoft Edge 團隊的 Lu Huang 和 Mandy Chen 指定及實作。這份文件由 Joe Medley 審查。