我該如何在 iOS WKWebView 中啟用 Universal Links? WKWebView 內部已經可以解析符合條件的 Universal Links。透過實作 WKNavigationDelegate,開發者可以自訂應用程式的路由策略,包含攔截應用程式自有連結、透過 decidePolicyForNavigationAction 控制外部轉跳,以及強制執行框架級別 (frame-level) 的安全性。
在 iOS 應用程式架構中,WKWebView 的導航攔截機制允許宿主應用程式針對 Universal Links、自訂 URL Scheme 和網頁目的地自訂路由政策。透過在 WKNavigationDelegate 中評估導航請求的元數據,應用程式能將自有內容導向至內部原生視圖,將外部目標交由系統處理,並強化框架層級的安全政策。
| 術語 | 定義 | 相關實體 | 搜尋意圖 |
|---|---|---|---|
| WebView | 內嵌式的 WebKit 元件,用於在 iOS 應用程式中呈現互動式網頁內容。 | iOS SDK | 資訊 / 商業 |
| Universal Links | 一種將受驗證的網域連結至 iOS 原生應用程式頁面的標準 HTTPS 機制。 | 深度連結路由 | 技術 / 資訊 |
| Custom URL Scheme | 應用程式定義的 URI Scheme,用於將 URL 導向原生應用程式。 | 行動深度連結 | 資訊 |
WKWebView 與 Universal Links 路由在 iOS 上的互動方式

WebKit 導航生命週期與應用程式自有路由政策
Apple 將 Universal Links 實作為一種系統級的路由機制,在 Safari 與 WKWebView 環境中皆受支援。當使用者點擊內嵌 WKWebView 中的合法連結時,系統可解析網域關聯並根據作業系統政策執行導航。
雖然系統認可的 Universal Links 可以將執行權交給原生處理器,但內嵌瀏覽器環境通常需要應用程式專屬的路由邏輯。例如,當連結指向應用程式自身網域時,開發者通常傾向於透過原生視圖控制器 (View Controllers) 直接呈現,而非觸發完整的外部 App 重啟程序。實作 WKNavigationDelegate 可讓開發團隊精細控制連結評估,不僅能強制執行自訂的允許清單,還能確保內部目的地路由的可預測性。
使用者體驗障礙:當 In-App 網頁將使用者困在重新導向循環中
內嵌 WebView 常被用於在 iOS App 內載入行銷微型網站、幫助中心、合作夥伴目錄與活動頁面。若網頁內的連結旨在將使用者導向應用程式的其他原生區塊(例如「在 App 中查看」按鈕)或是其他合作夥伴 App,預設的導航行為可能會導致冗餘的渲染:
- 冗餘網頁渲染:使用者被迫觀看 App 內頁面的網頁版本,而非原生視圖,這可能導致重複登入並破壞視覺一致性。
- 網頁循環陷阱:使用者可能被困在深層的網頁導航堆疊中,難以回到 App 的原生主介面。
- App 間轉跳失敗:點擊指向第三方服務(例如導航軟體、社群分享對話框或支付閘道)的連結時,若該服務依賴自訂 URL Scheme,則需要明確的程式委派才能正常運行。
比較 WKWebView 與 SFSafariViewController 的 Web-to-App 轉跳
在 iOS 建構內嵌網頁瀏覽體驗時,開發團隊必須在 WKWebView 與 SFSafariViewController 之間進行取捨:
SFSafariViewController:提供系統管理的獨立 Safari 瀏覽介面,具備自動填寫與內容阻擋功能。宿主 App 無法檢視瀏覽活動或網站資料,UI 自訂程度僅限於色調。WKWebView:一個嵌入在 App UI 進程中的視圖元件,並在獨立的 WebKit 進程中執行網頁內容。它支援高度 UI 自訂、JavaScript Bridge 以及自訂佈局整合,但需要明確實作WKNavigationDelegate來定義路由政策與處理自訂 Scheme。
decidePolicyForNavigationAction 如何攔截 WebKit 路由
導航政策管線:理解 WKNavigationAction、request 與 decisionHandler
為了控制 WKWebView 內部的導航流程,開發者需指派一個遵循 Apple WKNavigationDelegate 官方指南 的代理。核心攔截點為代理方法:
func webView(
_ webView: WKWebView,
decidePolicyFor navigationAction: WKNavigationAction,
decisionHandler: @escaping (WKNavigationActionPolicy) -> Void
)
由使用者互動、程式化重新導向或表單提交觸發的導航動作皆會經過此方法。WKNavigationAction 物件提供關鍵元數據:
navigationAction.request.url:請求的目標URL。navigationAction.navigationType:觸發類型(如.linkActivated,.other,.formSubmitted)。navigationAction.sourceFrame:發起導航請求的框架資訊。navigationAction.targetFrame:預計載入內容的目標框架資訊。
decisionHandler 是一個完成閉包 (completion closure),負責通知 WebKit 是否允許或取消請求的導航。
何時使用 .allow 與 .cancel:控制 WebKit 資源載入生命週期
傳遞給 decisionHandler 的 WKNavigationActionPolicy 決定了 WebKit 是否繼續導航:
.allow:通知 WebKit 在網頁視圖內繼續導航。.cancel:指示 WebKit 取消該導航。當宿主應用程式攔截自訂 Scheme、內部導向自有 Universal Links 或將外部目標轉交給UIApplication.shared.open()時,應執行此政策。
每個導航動作必須僅呼叫一次 decisionHandler,以確保政策解析正常完成而不致阻塞。
評估導航類型:區分使用者點擊 (.linkActivated) 與自動重新導向
WKNavigationAction.navigationType 讓開發者能區分明確的使用者互動與自動化指令:
.linkActivated:使用者物理觸發了 HTML 錨點 (<a href="...">)。.other:代表程式化導航,例如window.location.href更新、meta 自動跳轉或初始的webView.load()呼叫。.formSubmitted/.formResubmitted:代表表單 POST 或 GET 提交。
評估 navigationType 有助於應用程式強制執行保守的「顯式連結」政策。針對外部自訂 Scheme 的調用或第三方 App 轉跳,強制要求 .linkActivated 作為閘門,有助於防止背景指令觸發非預期的外部 App 啟動。
處理非同步決策政策並避免 Retain Cycles
當路由驗證或權限檢查需要在返回決策前查詢本機快取或安全驗證器時:
- 確保
decisionHandler在所有執行路徑中(包括錯誤與防護條件)均被執行。 - 在逃逸閉包 (escaping closures) 中使用弱引用 (
[weak self]),以避免WKWebView、其代理與父層UIViewController之間產生 retain cycles。
區分宿主 App 關聯網域與外部 Universal Links

管理自有目的地與系統級連結委派
對於自有路由,應避免試圖透過重複的 Universal Link 查找來重新進入應用程式。應直接透過宿主 App 的內部路由處理自有內容,並將系統層級開啟功能優先用於離開當前應用程式或需由外部服務解析的目的地。
此架構分離能確保流暢的導航:
- 宿主 App 關聯網域 (Associated Domains):若 URL host 符合 App 的關聯網域 (如
app.example.com),則取消網頁視圖導航 (decisionHandler(.cancel)),驗證路徑並直接將解析後的參數傳遞給應用程式的內部導航路由器。 - 外部應用程式:若 URL 指向外部合作夥伴目的地或允許的自訂 Scheme,應套用應用程式級的連結閘門 (
navigationType == .linkActivated),取消網頁視圖導航,並將請求轉發至UIApplication.shared.open(url),讓作業系統啟動對應 App。
建構內部路由驗證:透過 AppRouteValidator 提取路徑與參數
當進入的 URL 符合 App 的關聯網域時,該 URL 字串必須先通過嚴格的路由驗證器,才能觸發視圖控制器轉換。
AppRouteValidator 模型規範:
- 針對支援的內部路由清單(如
/open/,/product/,/promo/,/checkout/)驗證 URL 路徑。 - 提取查詢參數(如
id,promo,utm_source)。 - 強制執行字元集限制、長度邊界並拒絕重複鍵,最終返回一個乾淨的
ValidatedAppRoute資料結構。
透過系統 UIApplication 委派處理外部第三方 Universal Links

當 WKWebView 內的網頁連結到外部服務(如合作夥伴 App、社群平台或工具)時,宿主 App 可將路由權限委派給 iOS 系統:
let options: [UIApplication.OpenExternalURLOptionsKey: Any] = [
.universalLinksOnly: true
]
UIApplication.shared.open(url, options: options) { success in
if !success {
// 應用程式政策後備:若沒有原生 App 處理該 Universal Link,則載入網頁內容
}
}
使用 .universalLinksOnly 作為應用程式政策,可確保僅在系統已安裝能處理該 Universal Link 的原生 App 時,才會將使用者跳轉至 App 外部。
同時處理 HTTPS Universal Links 與自訂 URL Scheme (myapp://)
雖然 HTTPS Universal Links 是 iOS 上的標準深度連結,但 App 定義的自訂 Scheme (如 myapp:// 或 partnerapp://) 在行銷與合作夥伴整合中仍相當常見。
在統一的 WKNavigationDelegate 實作中:
- 優先檢查非 HTTP/HTTPS Scheme。若 Scheme 符合允許的協定且滿足顯式連結政策 (
navigationType == .linkActivated),代理會驗證 host、path 與參數,再發送至UIApplication.shared.open()。 - 不被認可的 Scheme 或非經使用者主動觸發的背景 Scheme 調用會立即取消,從而防止未處理的導航錯誤或腳本驅動的意圖濫用。
[使用者與 iOS WKWebView 連結互動]
│
▼
[WKNavigationDelegate: decidePolicyForNavigationAction]
│
┌─────────────┴─────────────┐
▼ ▼
[!action.sourceFrame.isMainFrame] [action.sourceFrame.isMainFrame]
│ │
▼ ▼
[子框架安全閘門] [檢查目的地 Scheme 與 Host]
├─ HTTP(S) -> .allow │
└─ 非網頁 -> .cancel ┌───────────┼───────────┐
(抑制子框架) ▼ ▼ ▼
[主網域] [外部網頁] [自訂 Scheme]
│ │ │
▼ ▼ ▼
[AppRoute] [檢查連結] [檢查連結]
├─ 有效 -> ├─ 夥伴 -> ├─ 有效且點擊 ->
│ 內部導向 │ 開啟 App │ 開啟 App
└─ 無效 -> └─ 網頁 -> └─ 無效/自動 ->
.cancel .allow .cancel
如何強制執行主框架安全性並防止 Iframe 劫持

將內嵌網頁導航視為不可信輸入:OWASP 深度連結安全標準
根據 OWASP 行動應用程式安全測試指南 (MASTG) 關於不安全深度連結的建議,行動導航處理器所處理的所有 URL 與參數載荷皆應視為不可信的外部輸入。
在 WKWebView 中呈現的網頁可能載入第三方腳本、廣告橫幅或使用者產生的內容。若導航代理未經驗證即將任意 URL 轉發至原生視圖控制器或 UIApplication.shared.open(),非預期的參數可能會攻擊敏感的內部應用程式路由。
將主框架導航與嵌入的 Iframes 及新視窗目標隔離
根據 Apple 開發者關於 WKNavigationAction 的技術文件,評估框架安全性需檢查發起框架:
sourceFrame.isMainFrame == true:導航由主層級文件框架直接發起。sourceFrame.isMainFrame == false:導航由嵌入的子框架或 iframe 發起。targetFrame == nil:導航請求一個新的視窗目標(如target="_blank"的錨點)。
為防止 iframe 劫持——即嵌入的 iframe 試圖在背景啟動外部應用程式或觸發原生視圖轉換——代理必須評估 sourceFrame.isMainFrame。若發起框架為 iframe (sourceFrame.isMainFrame == false),允許標準 HTTP/HTTPS 子框架導航 (.allow),但必須封鎖任何非網頁自訂 Scheme 或原生路由轉跳 (.cancel)。
防止惡意子框架協議調用與背景 Scheme 濫用
執行發起框架檢查可防止子框架觸發非預期的外部 Scheme 調用:
if !navigationAction.sourceFrame.isMainFrame {
let scheme = url.scheme?.lowercased() ?? ""
if scheme == "http" || scheme == "https" {
decisionHandler(.allow) // 允許標準 HTTP(S) 子框架導航
} else {
decisionHandler(.cancel) // 封鎖來自子框架的非網頁 Schemes
}
return
}
在用戶端路由中強制執行嚴格路徑與查詢參數允許清單
內部關聯網域 URL 與外部自訂 Scheme 皆必須通過嚴格的驗證模型才能執行:
- 路徑前綴允許清單:強制使用已批准的路由前綴 (如
/open/,/product/,/promo/,/checkout/),拒絕任意或畸形路徑。 - 查詢鍵過濾:拋棄非預期的查詢鍵並拒絕重複鍵,以防止參數污染。
- 資料型別與長度限制:將參數值限制為字母數字字元集,並設定最大長度限制 (≤ 64 字元)。
生產環境中的 Swift WKNavigationDelegate 實作
規劃 CustomWebViewController 與 Swift 代理架構
生產級的 WKWebView 控制器整合了網頁配置、導航政策評估、內部路由與外部委派。實作將驗證規則封裝在專用的驗證類別中(AppRouteValidator 與 CustomSchemeValidator),以保持代理回調的簡潔、可測試與安全性。
實作 AppRouteValidator 與 CustomSchemeValidator 模型
驗證器模型強制執行「預設封鎖」(fail-closed) 的安全機制:
AppRouteValidator驗證內部關聯網域,檢查路徑前綴並將查詢參數過濾為結構化的ValidatedAppRoute物件。CustomSchemeValidator檢查授權的自訂 Scheme (如myapp),驗證允許的 Host (如open,product,event),並過濾查詢值。
OpoInstall 可與應用程式的路由層整合,以進行歸因分析與延遲參數恢復。請查閱 SDK 整合文件 獲取完整指引。
下方的技術實作展示了如何在 Swift 中配置安全的 WKNavigationDelegate:
// iOS: 具備嚴格 WKNavigationDelegate 路由與框架安全的 CustomWebViewController
// 參考整合範例。請依據您的架構確認方法簽章與網域映射。
import UIKit
import WebKit
struct ValidatedAppRoute {
let path: String
let queryParams: [String: String]
}
// 1. 宿主 App 關聯網域驗證器 (內部路由)
class AppRouteValidator {
private static let allowedPrefixes = ["/open/", "/product/", "/promo/", "/checkout/"]
private static let allowedQueryKeys = Set(["target", "id", "promo", "utm_source"])
static func validate(url: URL) -> ValidatedAppRoute? {
let path = url.path
// 強制執行批准的路徑前綴允許清單
guard allowedPrefixes.contains(where: { path.hasPrefix($0) }) else {
return nil
}
var sanitizedParams: [String: String] = [:]
var seenKeys = Set<String>()
if let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
let queryItems = components.queryItems {
let validChars = CharacterSet(charactersIn: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-")
for item in queryItems {
// Fail-closed 驗證:若存在未經授權的查詢鍵或重複鍵,則拒絕該 URL
guard allowedQueryKeys.contains(item.name), !seenKeys.contains(item.name) else { return nil }
seenKeys.insert(item.name)
let value = item.value ?? ""
if value.count <= 64 && value.rangeOfCharacter(from: validChars.inverted) == nil {
sanitizedParams[item.name] = value
} else {
return nil
}
}
}
return ValidatedAppRoute(path: path, queryParams: sanitizedParams)
}
}
// 2. 外部自訂 Scheme 驗證器 (myapp://)
class CustomSchemeValidator {
private static let allowedSchemes = Set(["myapp"])
private static let allowedHosts = Set(["open", "product", "event"])
private static let allowedPathPrefixes = ["/detail/", "/view/", "/main/"]
private static let allowedQueryKeys = Set(["target", "id", "promo", "utm_source"])
static func validate(url: URL) -> URL? {
guard let scheme = url.scheme?.lowercased(), allowedSchemes.contains(scheme) else {
return nil
}
guard let host = url.host?.lowercased(), allowedHosts.contains(host) else {
return nil
}
let path = url.path
if !path.isEmpty && !allowedPathPrefixes.contains(where: { path.hasPrefix($0) }) {
return nil
}
var seenKeys = Set<String>()
if let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
let queryItems = components.queryItems {
let validChars = CharacterSet(charactersIn: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-")
for item in queryItems {
guard allowedQueryKeys.contains(item.name), !seenKeys.contains(item.name) else { return nil }
seenKeys.insert(item.name)
let value = item.value ?? ""
if value.count > 64 || value.rangeOfCharacter(from: validChars.inverted) != nil {
return nil
}
}
}
return url
}
}
// 3. 託管 WKWebView 並具備安全導航政策攔截功能的 UIViewController
class CustomWebViewController: UIViewController, WKNavigationDelegate {
var webView: WKWebView!
private let hostAssociatedDomain = "app.example.com"
private let allowedExternalPartnerHosts = Set(["partner.example.com"])
override func viewDidLoad() {
super.viewDidLoad()
let configuration = WKWebViewConfiguration()
webView = WKWebView(frame: view.bounds, configuration: configuration)
webView.navigationDelegate = self
view.addSubview(webView)
}
func webView(
_ webView: WKWebView,
decidePolicyFor navigationAction: WKNavigationAction,
decisionHandler: @escaping (WKNavigationActionPolicy) -> Void
) {
guard let url = navigationAction.request.url else {
decisionHandler(.allow)
return
}
// 安全檢查 1: 強制執行發起框架邊界 (sourceFrame) 以防止 iframe 劫持
if !navigationAction.sourceFrame.isMainFrame {
let scheme = url.scheme?.lowercased() ?? ""
if scheme == "http" || scheme == "https" {
decisionHandler(.allow) // 允許標準 HTTP(S) 子框架導航
} else {
decisionHandler(.cancel) // 封鎖來自子框架的非網頁 Schemes
}
return
}
let scheme = url.scheme?.lowercased() ?? ""
let isExplicitLinkActivation = (navigationAction.navigationType == .linkActivated)
// 安全檢查 2: 處理宿主 App 的關聯網域
// 進行內部導向,而非呼叫 UIApplication.shared.open
if scheme == "https", let host = url.host?.lowercased(), host == hostAssociatedDomain {
if let validatedRoute = AppRouteValidator.validate(url: url) {
AppInternalRouter.shared.navigate(to: validatedRoute)
}
decisionHandler(.cancel) // 取消 WebView 載入以便執行內部路由
return
}
// 安全檢查 3: 處理允許的自訂 Schemes (myapp://) 並套用連結點擊政策
if scheme != "http" && scheme != "https" && scheme != "about" {
// 強制要求自訂 Scheme 的外部啟動必須由使用者明確點擊觸發
if isExplicitLinkActivation, let validatedURL = CustomSchemeValidator.validate(url: url) {
UIApplication.shared.open(validatedURL, options: [:], completionHandler: nil)
}
decisionHandler(.cancel) // 取消 WebView 載入以防未處理的 Scheme 錯誤
return
}
// 安全檢查 4: 處理外部目的地與新視窗 (target="_blank") 請求
if scheme == "http" || scheme == "https" {
let host = url.host?.lowercased() ?? ""
// 針對受信任夥伴的 Universal Links 套用顯式連結政策並轉交外部 App
if allowedExternalPartnerHosts.contains(host) && isExplicitLinkActivation {
let options: [UIApplication.OpenExternalURLOptionsKey: Any] = [
.universalLinksOnly: true
]
UIApplication.shared.open(url, options: options) { [weak self] success in
if !success {
// 應用程式政策後備:若無原生 App 處理,則在 WebView 內載入外部夥伴內容
guard let self = self else { return }
self.webView.load(navigationAction.request)
}
}
decisionHandler(.cancel)
return
}
// 若 targetFrame 為 nil (新視窗請求),則在當前 webView 安全載入
if navigationAction.targetFrame == nil {
webView.load(navigationAction.request)
decisionHandler(.cancel)
return
}
// 標準網頁內容在 WKWebView 內持續載入
decisionHandler(.allow)
return
}
decisionHandler(.allow)
}
}
// 應用程式專屬的內部路由佔位器 (非 OpoInstall SDK API)
class AppInternalRouter {
static let shared = AppInternalRouter()
func navigate(to route: ValidatedAppRoute) {
// 根據路徑與參數執行內部 UI 視圖控制器轉換
}
}
執行緒安全:確保 UI 轉換在 Main Actor 上執行
在目前的 Swift 並發模型中,WKNavigationDelegate 回調受到 Main Actor 隔離。應用程式路由與視圖控制器轉換皆於主執行緒執行,維持跨原生導航工作流的執行緒安全。
WKWebView 深度連結導航錯誤與診斷矩陣
iOS WKWebView 深度連結疑難排解指南
下表列出了在 iOS WKWebView 中管理深度連結與自訂 Scheme 時常見的失效模式、根本原因與建議工程對策:
| 錯誤現象 | 主要根本原因 | 適用 iOS 版本 | 診斷檢查點 | 建議對策 |
|---|---|---|---|---|
| Universal Link 在 WebView 中載入 | 自有網域未被攔截 | iOS 9+ | decidePolicyForNavigationAction 未處理 |
攔截自有網域,解析路徑,執行內部路由,並回傳 .cancel |
| 自有網域連結無法路由 | 對自身網域呼叫 UIApplication.open |
iOS 9+ | 對自身 host 呼叫 UIApplication.shared.open |
避免外部自開,直接呼叫內部路由器 |
| 自訂 Scheme 無聲失敗 | WebKit 不識別非 HTTP 協定 | iOS 9+ | Scheme 未委派給 UIApplication |
在代理中攔截 Scheme,驗證允許清單,透過 UIApplication 開啟 |
| Iframe 協議劫持 | 子框架觸發外部自訂 Scheme | iOS 9+ | sourceFrame.isMainFrame 未檢查 |
使用 if !sourceFrame.isMainFrame 守門,並抑制非網頁 Schemes |
| UI 轉跳警告或轉換問題 | UI 轉換於背景執行緒執行 | iOS 9+ | 缺少 Main-Actor 排程 | 確保內部路由器與視圖控制器轉換皆於 Main-Actor 執行 |
常見問題 (FAQ)
開發者如何在 WKWebView 中攔截 Universal Links?
我可以使用 UIApplication.shared.open 從 WKWebView 啟動自己的 App 嗎?
如何防止 WKWebView 中的內嵌 iframe 觸發外部 App 啟動?
總結與決策框架
在 iOS WKWebView 內處理 Universal Links 與自訂 Scheme,需要架起 WebKit 網頁渲染容器與原生 UIKit 導航生命週期之間的橋樑。過度依賴預設的導航政策,往往會在需要自有路由邏輯時,造成轉換體驗不流暢。
透過實作一個強健的 WKNavigationDelegate,不僅能驗證框架邊界、在外部轉跳上強制執行保守的連結點擊政策、透過嚴格的路徑驗證器解析內部關聯網域,並將外部目標安全委派至 UIApplication.shared.open,工程團隊能保持高度的導航可控性,同時防範 iframe 協議劫持風險。
若要進一步了解原生 iOS 深度連結與參數路由架構,請參考 SDK 整合文件。
相關資源
-
概念:iOS WebView 路由、Universal Links 攔截、WKNavigationDelegate、框架邊界隔離
-
技術:Apple WebKit、iOS UIKit、WKWebView、OpoInstall iOS SDK
-
標準:IETF RFC 3986 統一資源識別碼、Apple 關聯網域規格 (Associated Domains)、OWASP 行動應用程式安全測試指南 (MASTG)
-
APIs:
WKNavigationDelegate.decidePolicyForNavigationAction,WKNavigationAction.sourceFrame,UIApplication.shared.open -
官方文件與參考:
Share this article



