PWA 的網址通訊協定處理常式註冊

讓已安裝的 PWA 處理使用特定通訊協定的連結，提供更整合的體驗。

Thomas Steiner

成功：PWA 的網址通訊協定處理常式註冊屬於功能專案的一部分，自 Chrome 96 版開始提供。

關於配置 (又稱為通訊協定) 的背景資訊

「統一資源識別碼」 (URI) 是一組精簡的字元，用於識別抽像或實體資源。每個 URI 的開頭都是架構名稱，該名稱會參照在該架構中指派 ID 的規格。因此，URI 語法是一種聯邦式可擴充的命名系統，其中每個配置的規格可進一步限制使用該配置的 ID 的語法和語意。也稱為通訊協定。以下提供一些配置的範例。

tel:[phone]
mailto:[e-mail]
news:comp.infosystems.www.servers.unix
https://web.dev/

「統一資源定位器」一詞 (URL) 是 URI 的子集，除了識別資源之外，還必須描述資源的主要存取機制 (例如網路位置)，提供尋找資源的方式。

registerProtocolHandler() 方法的背景資訊

僅限安全內容的 Navigator 方法 registerProtocolHandler()，可讓網站註冊開啟或處理特定網址配置的功能。因此，網站需要呼叫以下方法：navigator.registerProtocolHandler(scheme, url)。這兩個參數的定義如下：

• scheme：包含網站要處理的通訊協定。
• url：包含處理常式網址的字串。這個網址必須包含 %s，做為預留位置，並替換為要處理的已轉義網址。

此方案必須是安全清單中的方案 (例如 mailto、bitcoin 或 magnet)，或是以 web+ 開頭，並在 web+ 前置詞後方加上至少一個或多個 ASCII 小寫字母，例如 web+coffee。

為了清楚說明這項功能，以下提供流程的具體範例：

1. 使用者造訪 https://coffeeshop.example.com/ 網站，該網站會發出以下呼叫：navigator.registerProtocolHandler('web+coffee', 'coffee?type=%s')。
2. 稍後，使用者在造訪 https://randomsite.example.com/ 時，點選 <a href="web+coffee:latte-macchiato">All about latte macchiato</a> 等連結。
3. 這會導致瀏覽器前往以下網址：https://coffeeshop.example.com/coffee?type=web%2Bcoffee%3A%2F%2Flatte-macchiato。然後，搜尋字串的網址解碼值會讀取 ?type=web+coffee://latte-macchiato。

通訊協定處理的目的

目前的 PWA 網址通訊協定處理常式註冊機制，是透過資訊清單，在 PWA 安裝作業中提供通訊協定處理常式註冊。將 PWA 註冊為通訊協定處理常式後，當使用者在瀏覽器或平台專屬應用程式中點選具有特定配置 (例如 mailto、bitcoin 或 web+music) 的超連結時，已註冊的 PWA 就會開啟並接收網址。請注意，建議的資訊清單註冊方式和傳統 registerProtocolHandler() 在實際上扮演的角色非常相似，同時仍可提供互補的使用者體驗：

• 相似之處包括允許註冊的配置清單，以及參數的名稱和格式等。
• 以資訊清單為基礎的註冊作業雖然有細微差異，但可能有助於提升 PWA 使用者的體驗。舉例來說，除了使用者自行安裝 PWA 之外，以資訊清單為基礎的 PWA 註冊可能不需要其他使用者動作。

用途

• 在文書處理 PWA 中，文件中的使用者會遇到簡報連結，例如 web+presentations://deck2378465。使用者點選連結後，系統會在正確的範圍內自動開啟簡報 PWA，並顯示簡報投影片。
• 在特定平台的即時通訊應用程式中，使用者會在即時通訊訊息中收到 magnet 網址的連結。點選連結後，已安裝的 torrent PWA 會啟動並開始下載。
• 使用者已安裝音樂串流 PWA。當朋友分享歌曲連結 (例如 web+music://songid=1234&time=0:13)，使用者點選連結時，音樂串流 PWA 就會自動在獨立視窗中啟動。

如何為 PWA 註冊網址通訊協定處理常式

用於註冊網址通訊協定處理常式的 API 會在 navigator.registerProtocolHandler() 上緊密地建模。此時，這項資訊是透過新屬性 ("protocol_handlers") 中的網頁應用程式資訊清單，以宣告的方式傳遞，該物件會採用具有 "protocol" 和 "url" 兩個必要鍵的物件陣列。下列程式碼片段說明如何註冊 web+tea 和 web+coffee。這個值是包含處理常式網址的字串，以及逸出網址的必要 %s 預留位置。

{
  "protocol_handlers": [
    {
      "protocol": "web+tea",
      "url": "/tea?type=%s"
    },
    {
      "protocol": "web+coffee",
      "url": "/coffee?type=%s"
    }
  ]
}

多個應用程式註冊相同通訊協定

如果多個應用程式將自己註冊為相同配置的處理常式 (例如 mailto 通訊協定)，作業系統會向使用者顯示挑選器，讓他們決定要使用哪個已註冊的處理常式。

同一個應用程式註冊多個通訊協定

如上方程式碼範例所示，同一個應用程式可以為多個通訊協定註冊。

應用程式更新和處理常式註冊

處理常式註冊會與應用程式提供的最新資訊清單版本同步。有兩種情況：

• 更新內容會新增新的處理程序觸發事件處理程序註冊 (與應用程式安裝作業分開)。
• 移除處理常式的更新會觸發登錄處理常式的更新作業 (與解除安裝應用程式不同)。

開發人員工具中的通訊協定處理常式偵錯

透過「Application」>「Manifest」窗格，前往「Protocol Handlers」部分。您可以在此查看及測試所有可用的通訊協定。

例如安裝這個 PWA 示範。在「Protocol Handlers」部分中，輸入「americano」，然後按一下「Test protocol」，即可在 PWA 中開啟咖啡頁面。

示範

您可以在 Glitch 上觀看 PWA 的網址通訊協定處理常式註冊示範。

1. 請前往 https://protocol-handler.glitch.me/，安裝 PWA，然後在安裝完成後重新載入應用程式。瀏覽器已將 PWA 註冊為作業系統與 web+coffee 通訊協定的處理常式。
2. 在已安裝的 PWA 視窗中，按一下連結 https://protocol-handler-link.glitch.me/。系統會開啟包含三個連結的新瀏覽器分頁。按一下第一或第二個選項 (拿鐵瑪奇朵或美式咖啡)。瀏覽器現在會顯示提示，詢問您是否同意讓應用程式成為 web+coffee 通訊協定的通訊協定處理常式。如果你同意，PWA 就會開啟並顯示所選咖啡。
3. 如要與使用 navigator.registerProtocolHandler() 的傳統流程進行比較，請在 PWA 中按一下「Register protocol handler」按鈕。然後在瀏覽器分頁中按一下第三個連結 (chai)。這類應用程式也會顯示提示，但會在分頁中開啟 PWA，而不是在瀏覽器視窗中開啟。
4. 在平台專用應用程式 (例如 Windows 上的 Skype) 上傳送訊息給自己，其連結例如 <a href="web+coffee://americano">Americano</a>，然後按一下該連結。應該也會開啟已安裝的 PWA。

安全性考量

由於 PWA 安裝作業需要安全的內容，因此通訊協定處理程序會繼承這項限制。已註冊的通訊協定處理常式清單不會以任何方式公開在網路上，因此無法做為指紋向量使用。

非使用者啟動的導覽嘗試

系統嘗試以程式輔助方式導覽 (而非由使用者啟動) 時，可能不會開啟應用程式。自訂通訊協定網址只能在頂層瀏覽環境中使用，但無法用於 iframe 的網址等。

通訊協定許可清單

就像 registerProtocolHandler() 一樣，應用程式可以註冊用於處理的通訊協定許可清單。

同意提示

在第一次啟動 PWA 時，由於系統會叫用通訊協定，因此會向使用者顯示權限對話方塊。這個對話方塊會顯示應用程式名稱和來源，並詢問使用者是否允許應用程式處理通訊協定中的連結。如果使用者拒絕權限對話方塊，作業系統就會忽略已註冊的通訊協定處理常式。如要取消註冊通訊協定處理常式，使用者必須解除安裝註冊該處理常式的 PWA。如果使用者選取「記住我的選擇」並選取「禁止」，瀏覽器也會取消註冊通訊協定處理常式。

意見回饋

Chromium 團隊想瞭解你的 PWA 網址通訊協定處理常式註冊使用經驗。

請說明 API 設計

您覺得這個 API 有任何不如預期的運作方式嗎？還是你還需要實現想法或屬性呢？對安全性模型有任何疑問或意見嗎？在對應的 GitHub 存放區中提出規格問題，或在現有問題中加入您的想法。

回報實作問題

您發現 Chromium 實作錯誤嗎？還是採用與規格不同？ 請前往 new.crbug.com 回報錯誤。請務必盡可能提供詳細資訊，並在「Components」方塊中輸入 UI>Browser>WebAppInstalls，以便重現問題。Glitch 可讓您輕鬆快速地分享重現內容。

顯示 API 支援

您是否打算為 PWA 使用網址通訊協定處理常式註冊功能？您的公開支援可幫助 Chromium 團隊優先處理各項功能，並讓其他瀏覽器廠商瞭解支援這些功能的重要性。

請在 WICG Discourse 討論串中分享您打算如何使用這項功能。使用主題標記 #ProtocolHandler 傳送 Twitter 推文到 @ChromiumDev，並告訴我們您使用此應用程式的位置和方式。

實用連結

• 說明
• 規格草稿
• GitHub
• ChromeStatus
• Chromium 錯誤
• TAG 審查
• Discourse

特別銘謝

Fabio Rocha、Diego González、Connor Moody 和 Microsoft Edge 團隊的 Samuel Tang 實作並指定 PWA 的網址通訊協定處理常式註冊。本文由 Joe Medley 和 Fabio Rocha 審查。主頁橫幅圖片由 JJ Ying 提供，取自 Unsplash。