How to Load H5 Pages in iOS Apps at Native Speed Using NSURLProtocol

Introduction

In today's diversified environment, a popular mobile app often contains embedded H5 pages. For apps with many operational scenarios, both native and H5 pages coexist. To reduce development cost, developers may want native‑like loading speed for H5 pages.

Loading H5 inside an app is a common pain point for client developers. Besides the inherent UX gap between H5 and native, slow loading further harms user experience. The key idea is to pre‑store remote resource packages locally so that H5 loads instantly.

Solution Options

We need to decide how to obtain the resource package (CSS, JS, HTML, images) in advance to reduce network requests. Two approaches:

Embed the resource package during the app packaging phase.

Download the resource package dynamically at runtime.

For simple business, the first method works: each new page requires a new app version. However, for long‑term flexibility we prefer dynamic updates, especially on iOS where app store review is slow and users may not update.

Design of the Loading Process

The overall flow is illustrated below:

The diagram assumes the client already implements a

socket

layer protocol that maintains a long connection with the

server

, allowing the server to push data. If such a protocol is unavailable, the client must periodically request the server for updates.

The following steps describe a complete download of a new resource package:

The operations team creates a new page for a holiday, generates a resource package in the backend, and updates the config with version, downgrade policy, and optional hot‑patch scripts, then deploys the package to a remote database.

At an appropriate moment, the

client

sends an HTTP request to the

server

to check for a new package, including the local config .

The

server

compares the received config with the client’s version; if the client is outdated, the server returns a new config and the resource package (optionally via CDN).

The

client

decrypts and decompresses the package, maps its files to local URLs (e.g., mapping

http://www.baidu.com

resources to

file://...

paths).

At this point the resource package has been downloaded.

Intercepting and Loading the Local Resource Package

To achieve native‑speed loading, the app intercepts H5 requests; if a matching local static file exists, it is loaded directly, resulting in a “instant” WebView.

On iOS this is done with NSURLProtocol . NSURLProtocol lets you redefine the behavior of Apple’s URL Loading System. When a request is made, the system creates an instance of an NSURLProtocol subclass, which can decide whether to handle the request.

In short, NSURLProtocol can intercept all network requests within the app and process them customly.

Key methods:

<code>+ (BOOL)canInitWithRequest:(NSURLRequest *)request</code>

Determines whether the protocol should handle the given request.

<code>+ (NSURLRequest *)canonicalRequestForRequest:(NSURLRequest *)request</code>

Allows preprocessing of the request; here we simply return the original request.

<code>- (void)startLoading</code>

Here we construct an

httpResponse

from the local file and pass it to

self.client

, which the WebView receives as if it came from the network.

It is important to set a flag such as

[NSURLProtocol setProperty:@YES forKey:WDHybridResourceProtocolHandledKey inRequest:newRequest];

to avoid infinite recursion when the local file is missing and a new request is issued.

When a request must be forwarded, the protocol should implement

NSURLConnectionDelegate

to perform the network request.

Conclusion

The article has covered the entire process of achieving fast H5 loading in iOS apps.

Performance comparison before and after applying the technique:

Note: This article was originally published on the JianShu platform by the author kuailejim, a company employee.