從 Chrome 122 開始,您可以訂閱 scope_extensions 應用程式資訊清單成員的來源試用,讓控制多個子網域和頂層網域的網站以單一網頁應用程式的形式呈現。本文將說明 Chrome 團隊推出這項功能的原因,以及您可能需要使用這項功能的時機。
總覽
部分網頁應用程式有多個來源,例如 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 盡可能像單一網頁應用程式一樣運作。

Scope Extensions 可讓多來源 PWA 在網頁應用程式 UI 方面,表現得像連續的網頁應用程式。
具體來說,這代表兩個更明確的目標:
- 跨源導覽:允許使用者在相關來源之間瀏覽,而不會叫用視窗 UI 告知使用者他們正在離開 PWA,進而干擾使用者體驗。
- 跨源連結擷取:允許網頁應用程式擷取使用者前往相關網站的導覽。
跨源範圍內導覽
根據預設,使用者在獨立 PWA 中跨來源瀏覽時,系統會顯示視窗 UI,指出他們正在離開 PWA 體驗。在 Chrome 中,這個 UI 包含「超出範圍」列,其中包含新來源的網址。使用者會預期在同一個應用程式環境中繼續瀏覽,但可能會覺得自己被帶離該環境,因此這種做法會干擾使用者體驗。

使用者在獨立 PWA 中瀏覽不同來源時,Chrome 會顯示「超出範圍」列。
使用範圍擴充功能時,當使用者前往任何相關聯來源時,系統不會顯示視窗 UI,因此 PWA 會呈現統一的體驗。
跨源連結擷取
連結擷取是指應用程式擷取其範圍內連結的能力。這項功能的實作方式因瀏覽器和作業系統而異。舉例來說,在 ChromeOS 的 Chrome 中,已安裝 PWA 範圍內的連結預設會開啟瀏覽器分頁,並在網址列中顯示有應用程式可以處理這些連結,讓使用者可以選擇加入從該點自動擷取連結。

ChromeOS 分頁的 Chrome 網址列片段,顯示連結可由 PWA 處理的視覺指示,以及記住該決定的選項。
如果使用者點選 PWA 範圍外的連結 (包括子網域或頂層網域的連結),系統不會將其視為 PWA 的一部分。舉例來說,連結會在瀏覽器分頁中開啟,而不會向使用者顯示有應用程式可以處理該連結。Scope Extensions API 可擴充 PWA 的範圍,將相關聯的來源視為範圍內連結。
導入
如要實作範圍擴充功能,必須建立主要來源與相關聯來源之間的關係。
宣告相關聯來源清單
在主要 PWA 來源中新增 scope_extensions 網頁應用程式資訊清單成員,讓網頁應用程式將範圍擴展至其他來源。
網頁應用程式資訊清單 (https://example.com)
{
"id": "/",
"name": "Example",
"display": "standalone",
"start_url": "/index.html",
"scope_extensions": [
{ "type": "origin", "origin": "https://help.example.com" },
{ "type": "origin", "origin": "https://example.co.uk" },
{ "type": "origin", "origin": "https://help.example.co.uk" }
]
}
確認關聯
列出的每個來源都會使用 /.well-known/web-app-origin-association 設定檔,確認與網頁應用程式的關聯。這個檔案必須命名為 web-app-origin-association,並在確切位置提供,因為這是已知 URI。
/.well-known/web-app-origin-association (關聯來源)
{
"https://example.com/": {
"scope": "/"
}
}
這個檔案會列出與來源相關聯的網頁應用程式。每個鍵都是網頁應用程式的資訊清單 ID,每個值都可以設定與相關聯來源相關的選用範圍。如果未指定範圍,則預設為「/」。
示範
示範包含兩個網站:
- 主要 PWA:實際的 PWA,透過網頁應用程式資訊清單中的
scope_extensions成員宣告相關聯來源清單。 - 擴充範圍內的來源:主要 PWA 範圍外的來源,但主要 PWA 將其列為相關聯來源,並透過其
web-app-origin-association檔案確認關係後,該來源就會與主要 PWA 建立關聯。
如要執行下列測試,您必須啟用 about://flags/#enable-desktop-pwas-scope-extensions 旗標 (適用於 Chrome 115 以上版本)。
測試跨源導覽
在瀏覽器中開啟主要 PWA,將其安裝為 PWA,然後開啟並在獨立模式下執行,這是進行這些測試的必要條件。PWA 包含擴充範圍內來源和擴充範圍外來源的連結。

示範 PWA,其中包含擴充範圍內和擴充範圍外的來源連結。
預設跨源導覽 (不在擴充範圍內)
- 在全螢幕 PWA 中,按一下來源不在擴充範圍內的連結。
- 因此,系統會執行導覽,並顯示超出範圍列。

在獨立模式下,PWA 跨來源導覽時,預設會顯示「超出範圍」列。
使用範圍擴充功能進行跨源導覽 (在擴充範圍內)

使用範圍擴充功能建立來源關聯後,跨源導覽不會顯示「超出範圍」列。
測試跨源連結擷取

點選 PWA 相關來源的連結,系統會在新分頁開啟連結,並顯示「在應用程式中開啟」圖示,讓使用者選擇加入自動擷取連結。
來源試用
如要在應用程式中,與實際使用者一起測試這個 API,可以透過來源試用進行。來源試用可讓您取得與網域綁定的測試權杖,與使用者一起試用實驗功能。接著,您可以部署應用程式,並預期該應用程式可在支援您測試功能的瀏覽器中運作 (在本例中,Chrome 121 至 126 版支援該功能)。如要取得自己的權杖來執行來源試用,請填寫申請表單。
意見回饋
Chrome 團隊正在徵求意見回饋,瞭解這個 API 的實用性。為協助團隊根據 API 實用性的意見回饋,以及目前版本未涵蓋的新用途,持續改進這項 API,請在 GitHub 上提出問題。
其他資源
- Scope Extensions API - 來源試用
- Chrome 狀態 - 網頁應用程式範圍擴充功能
- 網頁應用程式範圍擴充功能說明
- 實驗意圖
- Mozilla 標準立場
- Apple 標準立場
- Chromium 錯誤
- 多來源網站中的漸進式網頁應用程式
- 在同一個網域上建構多個漸進式網頁應用程式
特別銘謝
特別感謝開發這個 API 的團隊。範圍擴充功能由 Alan Cutter 和黃璐指定,並由 Matt Giuca 提供輸入內容。這個 API 是由 Google Chrome 的 Alan Cutter,以及 Microsoft Edge 的 Hassan Talat、Kristin Lee 和Lu Huang 實作。