網頁應用程式範圍擴充功能

從 Chrome 122 開始，您可以訂閱scope_extensions應用程式資訊清單成員的原始試用，讓控管多個子網域和頂層網域的網站顯示為單一網頁應用程式。本文說明 Chrome 團隊推出這項功能的原因，以及您可能想使用這項功能的情況。

Demián Renzulli

Thomas Steiner

總覽

部分網頁應用程式有多個來源，例如 example.com 是主要應用程式，然後 space_1.example.com、…、space_n.example.com (有時會與 special-example.com 結合) 是子體驗，全部都屬於主要應用程式。這類網站架構會對漸進式網頁應用程式造成影響。限制包括無法在來源之間共用 Service Worker、任何類型的裝置、本機儲存空間和權限。此外，獨立 PWA 中的跨來源導覽會顯示視窗 UI (「超出範圍」列)，指出使用者已離開 PWA 體驗。如要瞭解如何解決部分問題，請參閱「多來源網站中的漸進式網頁應用程式」和「在同一網域中建構多個漸進式網頁應用程式」這兩篇文章。

透過 Scope Extensions API，網頁應用程式可以克服同源政策對這類網站架構造成的某些挑戰。網頁應用程式可藉此將範圍擴展至其他來源，前提是網頁應用程式的主要來源和相關聯來源已達成共識，以利提供一致的體驗。

目標

Scope Extensions API 的主要目標是讓控制多個子網域和頂層網域的網站，在網頁應用程式 UI 和連結擷取方面，能以一個連續的網頁應用程式運作。舉例來說，讓跨越 example.com.co.uk 和 support.example.com 的網站 example.com 盡可能像單一網頁應用程式一樣運作。

圖表：顯示主要 PWA 和相關聯的子體驗。

範圍擴充功能可讓多來源 PWA 在網頁應用程式 UI 方面，表現得像連續的網頁應用程式。

實際上，這會轉化為兩個更具體的目標：

跨來源導覽：允許使用者在相關聯的來源之間導覽，不會因為叫用視窗 UI 而中斷使用者體驗，並告知使用者即將離開 PWA。
跨來源連結擷取：允許網頁應用程式擷取使用者前往相關網站的導覽動作。

範圍內的跨來源導覽

根據預設，使用者在獨立 PWA 中跨來源瀏覽時，系統會顯示視窗 UI，指出他們即將離開 PWA 體驗。在 Chrome 中，這個 UI 會顯示「超出範圍」列，其中包含新來源的網址。使用者原本預期會在同一個應用程式環境中繼續瀏覽，但可能會覺得自己被帶離該環境，因此這種做法會干擾使用者體驗。

獨立 PWA 頂端的範圍外列。

使用者在獨立 PWA 中瀏覽不同來源時，Chrome 會顯示「超出範圍」列。

使用範圍擴充功能時，使用者瀏覽任何相關聯的來源時，系統都不會顯示視窗 UI，因此 PWA 會呈現統一的體驗。

擷取跨來源連結

連結擷取是指應用程式擷取範圍內連結的功能。實作方式會因瀏覽器和作業系統而異。舉例來說，在 ChromeOS 上的 Chrome 中，已安裝 PWA 範圍內的連結預設會開啟瀏覽器分頁，網址列會顯示有應用程式可處理這些連結，讓使用者從該處選擇自動擷取連結。

已安裝 PWA 的網址列提示。

ChromeOS 分頁的 Chrome 網址列片段，顯示連結可由 PWA 處理的視覺指標，以及記住該決定的選項。

如果使用者點按 PWA 範圍外的連結 (包括子網域或頂層網域的連結)，系統不會將其視為屬於 PWA。舉例來說，連結會在瀏覽器分頁中開啟，但不會向使用者指出有應用程式可以處理該連結。Scope Extensions API 可擴展 PWA 的範圍，讓相關聯的來源視為範圍內的連結。

導入作業

如要實作範圍擴充功能，必須建立主要來源與相關聯來源之間的關係。

宣告相關聯的來源清單

在主要 PWA 來源中新增 scope_extensions 網頁應用程式資訊清單成員，讓網頁應用程式將範圍擴展至其他來源。

網頁應用程式資訊清單 (https://example.com)

{
  "name": "Example",
  "display": "standalone",
  "start_url": "/index.html",
  "scope_extensions": [
    { "origin": "https://*.example.com" },
    { "origin": "https://example.co.uk" },
    { "origin": "https://*.example.co.uk" }
  ]
}

確認關聯

每個列出的來源都會使用 /.well-known/web-app-origin-association 設定檔，確認與 Web 應用程式的關聯。這個檔案必須命名為 web-app-origin-association，並在這個確切位置提供服務，因為這是 Well-Known URI。

/.well-known/web-app-origin-association (相關聯的來源)

{
  "web_apps": [{ "web_app_identity": "https://example.com" }]
}

示範

這個示範包含兩個網站：

主要 PWA：實際的 PWA，透過網頁應用程式資訊清單中的 scope_extensions 成員宣告相關聯的來源清單。
擴大範圍中的來源：主要 PWA 範圍外的來源，但列為相關聯的來源並透過 web-app-origin-association 檔案確認關係後，即與主要 PWA 相關聯。

如要執行下列測試，請啟用 about://flags/#enable-desktop-pwas-scope-extensions 標記 (適用於 Chrome 115 以上版本)。

測試跨原始來源導覽

執行這些測試的前提是，在瀏覽器中開啟主要 PWA，並將其安裝為 PWA，然後開啟以獨立模式執行。PWA 包含擴充範圍內的來源連結，以及擴充範圍外的來源連結。

主要 PWA 視窗，其中包含範圍內和範圍外的連結。

示範 PWA，其中包含連至擴充範圍內來源的連結，以及連至擴充範圍外來源的連結。

預設跨來源導覽 (不在擴充範圍內)

在全螢幕 PWA 中，按一下「origin not in extended scope」(不在擴充範圍內的來源) 連結。
因此系統會進行導覽，並顯示範圍外的資訊列。

點選範圍外連結後，主要 PWA 視窗會顯示範圍外列。

如果 PWA 處於獨立模式，且導覽為跨來源導覽，系統預設會顯示「超出範圍」列。

使用範圍擴充功能 (在擴充範圍內) 進行跨來源導覽

返回 PWA 的首頁。
按一下連結，前往不在擴展範圍內的來源。
根據預設，系統應會顯示「超出範圍」列，但由於 Scope Extensions 關聯，因此不會顯示。

點選擴大範圍連結後，主要 PWA 視窗不會顯示超出範圍的橫幅。

與範圍擴充功能建立來源關聯後，跨來源導覽中不會顯示「超出範圍」列。

測試跨來源連結擷取功能

在 ChromeOS 裝置上開啟並安裝主要 PWA。
按一下下列連結：相關聯的來源。
連結會在新的瀏覽器分頁中開啟，並顯示提示，要求在已安裝的 PWA 中開啟。

已安裝的 PWA 範圍擴大，網址列會顯示提示。

點選與 PWA 相關聯來源的連結時，連結會在新的分頁中開啟，並顯示「在應用程式中開啟」圖示，讓使用者選擇是否要自動擷取連結。

來源試用

如要在應用程式中，與實際使用者一起測試這個 API，可以透過原始碼試用進行測試。您可以取得與網域相關聯的測試權杖，與使用者一起試用實驗功能。接著，您可以部署應用程式，並預期應用程式會在支援您測試功能的瀏覽器中運作 (在本例中，Chrome 121 到 126 版支援這項功能)。如要取得自己的權杖來執行原始碼試用，請填寫申請表單。

意見回饋

Chrome 團隊希望瞭解這項 API 是否實用，如要協助團隊根據實用性回饋和目前版本未涵蓋的新用途，進一步開發這項 API，請在 GitHub 上開啟問題。

其他資源

特別銘謝

特別感謝這個 API 的開發團隊。範圍擴充功能由 Alan Cutter 和 Lu Huang 指定，並由 Matt Giuca 提供意見。這項 API 由 Google Chrome 的 Alan Cutter 和 Microsoft Edge 的 Hassan Talat、Kristin Lee 和 Lu Huang 實作。