WKWebView is the foundation for in-app browsing in iOS apps. It is fast, modern, and supports the same JavaScript engine as Safari. But its relationship with Universal Links is different from Safari's, and if you do not configure it correctly, Universal Links tapped inside your WebView will behave in unexpected ways.<\/p>\n\n\n\n
This article explains how WKWebView processes navigation, how to intercept Universal Links before they escape the WebView context, and the common pitfalls that cause deep linking to fail inside embedded web views.<\/p>\n\n\n\n
For Universal Links fundamentals, see universal links: everything you need to know<\/a>. For Safari-specific behaviors, see universal links in Safari: behavior and edge cases<\/a>.<\/p>\n\n\n\n In Safari, tapping a Universal Link triggers the system's URL dispatcher. iOS checks the Associated Domains entitlement, finds the matching app, and opens it. This happens at the OS level.<\/p>\n\n\n\n WKWebView is a UI component that renders web content inside your app's process. It does not automatically defer URL navigation to the iOS dispatcher the way Safari does. When a user taps a link inside a WKWebView, the WebView intercepts that navigation internally. Without explicit configuration, Universal Links tapped inside a WKWebView will simply load as regular web pages inside the WebView, not open the app (or another app).<\/p>\n\n\n\n This is a documented behavior difference. Apple's WKWebView documentation<\/a> notes that WKWebView does not participate in the Universal Links dispatch chain automatically.<\/p>\n\n\n\n The right place to intercept Universal Links in WKWebView is The key decision is when to call If your WebView is loading your own domain and you want Universal Links to open specific native screens, intercept the navigation and route internally:<\/p>\n\n\n\n This pattern keeps the user in a native flow rather than loading a web page for content that has a native equivalent.<\/p>\n\n\n\n WKWebView has an If link previews create issues with your navigation policy, disable them:<\/p>\n\n\n\n Apple's documentation on this property is at WKWebView.allowsLinkPreview<\/a>.<\/p>\n\n\n\n Universal Links often involve redirects. A short link might redirect to your Universal Link domain. The However, server-side redirects (HTTP 301\/302) arrive as a different navigation action type. Use Not setting the navigation delegate.<\/strong> If Forgetting to call Checking the wrong navigation action type.<\/strong> Not accounting for JavaScript-initiated navigation.<\/strong> Single-page applications often use JavaScript to change the URL (via Missing back-navigation handling.<\/strong> If you cancel a navigation and open the native app, the WebView stays on the previous page. Make sure the user experience makes sense. You may want to dismiss the WebView, depending on your app's flow.<\/p>\n\n\n\n Apple introduced Tolinku<\/a> manages your AASA file and route configuration. When a user taps a Tolinku-managed deep link inside your WKWebView, your For SFSafariViewController as an alternative, see SFSafariViewController and deep links: best practices<\/a>. For the complete Universal Links guide, see universal links: everything you need to know<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":" Configure WKWebView to handle Universal Links correctly. Learn delegation, navigation policies, and common WebView deep linking issues.<\/p>\n","protected":false},"author":2,"featured_media":2040,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"rank_math_title":"Handling Universal Links in WKWebView: A Developer Guide","rank_math_description":"Configure WKWebView to handle Universal Links correctly. Learn delegation, navigation policies, and common WebView deep linking issues.","rank_math_focus_keyword":"WKWebView universal links","rank_math_canonical_url":"","rank_math_facebook_title":"","rank_math_facebook_description":"","rank_math_facebook_image":"https:\/\/tolinku.com\/blog\/wp-content\/uploads\/2026\/03\/og-wkwebview-universal-links.png","rank_math_facebook_image_id":"","rank_math_twitter_title":"","rank_math_twitter_description":"","rank_math_twitter_image":"https:\/\/tolinku.com\/blog\/wp-content\/uploads\/2026\/03\/og-wkwebview-universal-links.png","footnotes":""},"categories":[11],"tags":[648,20,315,24,650,31,22,649,325,569],"class_list":["post-2041","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-deep-linking","tag-app-development","tag-deep-linking","tag-in-app-browser","tag-ios","tag-navigation-delegate","tag-swift","tag-universal-links","tag-webkit","tag-webview","tag-wkwebview"],"_links":{"self":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts\/2041","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/comments?post=2041"}],"version-history":[{"count":1,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts\/2041\/revisions"}],"predecessor-version":[{"id":2042,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts\/2041\/revisions\/2042"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/media\/2040"}],"wp:attachment":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/media?parent=2041"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/categories?post=2041"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/tags?post=2041"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}Why WKWebView Handles Universal Links Differently<\/h2>\n\n\n\n
The WKNavigationDelegate<\/h2>\n\n\n\n
WKNavigationDelegate<\/code>. Specifically, you implement webView(_:decidePolicyFor:decisionHandler:)<\/code> to evaluate every navigation action before it happens.<\/p>\n\n\n\nimport WebKit\n\nclass WebViewController: UIViewController, WKNavigationDelegate {\n\n var webView: WKWebView!\n\n override func viewDidLoad() {\n super.viewDidLoad()\n\n let config = WKWebViewConfiguration()\n webView = WKWebView(frame: view.bounds, configuration: config)\n webView.navigationDelegate = self\n view.addSubview(webView)\n\n if let url = URL(string: "https:\/\/yourdomain.com") {\n webView.load(URLRequest(url: url))\n }\n }\n\n func webView(\n _ webView: WKWebView,\n decidePolicyFor navigationAction: WKNavigationAction,\n decisionHandler: @escaping (WKNavigationActionPolicy) -> Void\n ) {\n guard let url = navigationAction.request.url else {\n decisionHandler(.allow)\n return\n }\n\n \/\/ Check if this URL is a Universal Link for another app\n if isUniversalLink(url) {\n UIApplication.shared.open(url, options: [:]) { success in\n if !success {\n \/\/ App not installed or link not handled, fall back to web\n }\n }\n decisionHandler(.cancel)\n return\n }\n\n decisionHandler(.allow)\n }\n\n private func isUniversalLink(_ url: URL) -> Bool {\n let universalLinkDomains = ["app.yourdomain.com", "yourdomain.com"]\n guard let host = url.host else { return false }\n return universalLinkDomains.contains(host)\n }\n}\n<\/code><\/pre>\n\n\n\ndecisionHandler(.cancel)<\/code> versus decisionHandler(.allow)<\/code>. Calling .cancel<\/code> stops the WebView from loading the URL. Calling .allow<\/code> lets the WebView proceed normally.<\/p>\n\n\n\nHandling Your Own App's Universal Links Inside a WebView<\/h2>\n\n\n\n
func webView(\n _ webView: WKWebView,\n decidePolicyFor navigationAction: WKNavigationAction,\n decisionHandler: @escaping (WKNavigationActionPolicy) -> Void\n) {\n guard let url = navigationAction.request.url else {\n decisionHandler(.allow)\n return\n }\n\n \/\/ Route internal Universal Links to native screens\n if url.host == "yourdomain.com", let path = routeToNativeScreen(url) {\n navigateToScreen(path)\n decisionHandler(.cancel)\n return\n }\n\n decisionHandler(.allow)\n}\n\nprivate func routeToNativeScreen(_ url: URL) -> String? {\n let path = url.path\n switch path {\n case let p where p.hasPrefix("\/product\/"):\n return "product"\n case let p where p.hasPrefix("\/checkout"):\n return "checkout"\n default:\n return nil\n }\n}\n<\/code><\/pre>\n\n\n\nThe
allowsLinkPreview<\/code> Property<\/h2>\n\n\n\nallowsLinkPreview<\/code> property that enables iOS's peek-and-pop or link preview behavior when users long-press a link. This uses a separate code path than decidePolicyFor<\/code> and can sometimes bypass your navigation policy.<\/p>\n\n\n\nwebView.allowsLinkPreview = false\n<\/code><\/pre>\n\n\n\nHandling Redirects<\/h2>\n\n\n\n
decidePolicyFor<\/code> delegate method is called for each navigation step, including redirects, so your policy check applies throughout the redirect chain.<\/p>\n\n\n\nWKNavigationDelegate<\/code>'s response-based delegate method to inspect the response after the server responds:<\/p>\n\n\n\nfunc webView(\n _ webView: WKWebView,\n decidePolicyFor navigationResponse: WKNavigationResponse,\n decisionHandler: @escaping (WKNavigationResponsePolicy) -> Void\n) {\n guard let httpResponse = navigationResponse.response as? HTTPURLResponse else {\n decisionHandler(.allow)\n return\n }\n\n \/\/ Inspect the final URL after any redirects\n let finalURL = httpResponse.url\n decisionHandler(.allow)\n}\n<\/code><\/pre>\n\n\n\nCommon Pitfalls<\/h2>\n\n\n\n
webView.navigationDelegate<\/code> is not set to your controller, decidePolicyFor<\/code> is never called and all navigation proceeds unchecked.<\/p>\n\n\n\ndecisionHandler<\/code>.<\/strong> Every path through decidePolicyFor<\/code> must call the decisionHandler<\/code> closure exactly once. Failing to call it causes an assertion failure, and calling it twice causes undefined behavior. Use guard<\/code> statements that always reach a decisionHandler<\/code> call.<\/p>\n\n\n\nWKNavigationAction<\/code> has a navigationType<\/code> property (.linkActivated<\/code>, .formSubmitted<\/code>, .reload<\/code>, .backForward<\/code>, etc.). You may want to apply your Universal Link check only to .linkActivated<\/code> navigations:<\/p>\n\n\n\nguard navigationAction.navigationType == .linkActivated else {\n decisionHandler(.allow)\n return\n}\n<\/code><\/pre>\n\n\n\nhistory.pushState<\/code> or location.href<\/code>). These navigations may arrive as .other<\/code> navigation type. If your SPA uses Universal Link paths, your policy check needs to handle those too.<\/p>\n\n\n\niOS 16.4+ Navigation Delegate Changes<\/h2>\n\n\n\n
webView(_:decidePolicyFor:preferences:decisionHandler:)<\/code> (with a WKWebpagePreferences<\/code> parameter) as an alternative to the older signature. If you implement both, only the newer version is called on iOS 16.4 and later. Check the WKNavigationDelegate reference<\/a> for the current recommended signature for your deployment target.<\/p>\n\n\n\nTolinku for WKWebView Deep Links<\/h2>\n\n\n\n
decidePolicyFor<\/code> implementation sees the URL on your Tolinku domain (subdomain or custom domain). You can check that domain in your isUniversalLink<\/code> function and route accordingly. See the Universal Links developer guide<\/a> for how to configure your domain for deep linking.<\/p>\n\n\n\n