Mastering WKWebView: Common Pitfalls, Multi‑Process Model, and Practical Solutions

Basic Review

Developers familiar with iOS/macOS hybrid development know that WKWebView, introduced as a replacement for UIWebView/WebView, often feels cumbersome despite its advertised advantages, and the community resources are outdated or low‑quality.

iOS Network Design and Cookie Management

iOS network layers can be reviewed through official documentation, but for clarity we focus on two fundamentals relevant to later discussions: iOS network design with cookie management and WKWebView's multi‑process model.

The network stack from top to bottom consists of:

WebKit: the application layer where the app and WKWebView reside.

NSURL: a wrapper over CoreFoundation interfaces, including NSURLConnection and NSURLSession.

CFNetwork: the core implementation layer handling protocol assembly, sending, and receiving.

BSD socket: low‑level socket services.

Cookie handling is performed in the CFNetwork layer; the "Set‑Cookie" header in responses is consumed there.

WKWebView Multi‑Process Model

Unlike UIWebView, WKWebView runs its core modules in separate processes from the app, which introduces many of the issues discussed later.

WKWebView runs its core modules in an independent process at runtime, separate from the app process.

WKWebView uses three processes:

UI Process – the app process that launches other processes.

Networking Process – handles all network requests; a single instance is shared among all WKWebView objects.

WebContent Process – runs WebCore and JSC; each WKWebView gets its own WebContent process.

All processes communicate via CoreIPC.

Main Issues and Solutions

In production, WKWebView presents four typical problems:

Request proxy issues

Cookie management issues

Full‑screen (notch) adaptation issues

WebContent process crashes

1. Request Proxy Issue

Apple does not allow WKWebView requests to be intercepted for security reasons, yet many business scenarios (offline packages, traffic monitoring) require proxying.

Two common work‑arounds are:

Register a custom scheme via WKBrowsingContextController registerSchemeForCustomProtocol: (Proxy 1).

Use WKWebViewConfiguration setURLSchemeHandler:forURLScheme: (Proxy 2) available from iOS 11.

Proxy 1 works on iOS 9‑14 but requires injecting JavaScript to serialize request bodies because the body is stripped when the request is handed to the app process.

Drawbacks of Proxy 1 include a blanket effect on all WKWebView instances and difficulty guaranteeing complete JavaScript overrides for sync requests, streaming uploads, and Fetch API streams.

Proxy 2 binds the handler to a specific WKWebView instance, avoiding the blanket effect and reducing the need to rewrite all request logic, but it is limited to iOS 11.3+ and still suffers from bugs such as multi‑image fragment download ordering and sync AJAX crashes.

2. Cookie Management Issue

WKWebView stores cookies in CFNetwork, leading to perceived isolation from the app’s cookie store. In reality, Session cookies are isolated per process, while persistent cookies are synchronized with a delay (300 ms – 3 s).

Key points:

Session cookies exist only in memory and are not shared between the app and WKWebView processes.

Persistent cookies are written to disk and eventually synchronized.

For iOS 11+, WKHTTPCookieStore can read, write, and observe cookie changes. For earlier versions, developers must force synchronization via private APIs such as _saveCookies and manually handle the SessionOnly attribute.

Synchronization strategy:

When the app process receives a Set‑Cookie header, persist the session cookie temporarily, invoke _saveCookies, then restore the session cookie.

When JavaScript modifies document.cookie, forward the change to the app process via a bridge.

3. Full‑Screen Adaptation Issue

WKWebView’s handling of viewport‑fit=cover differs from UIWebView; if the page’s body height does not exceed the WKWebView height, the safe‑area insets may be ignored. The workaround is to ensure the body height uses 100vh or similar techniques.

4. WebContent Process Crash Issue

When the WebContent process crashes, WKWebView triggers webViewWebContentProcessDidTerminate. Reloading the page often restores functionality, but if the crash occurs during a critical operation (e.g., image upload), the user experience can be severely impacted. No universal fix exists; developers should design graceful recovery paths and, where possible, persist intermediate state.

Conclusion

WKWebView’s design introduces several friction points—request proxying, cookie isolation, full‑screen adaptation, and occasional process crashes—largely because the system was not built with modern hybrid app requirements in mind. Understanding the underlying multi‑process architecture and employing the outlined work‑arounds can mitigate most issues, but developers must remain aware of platform limitations and test across iOS versions.