How Huolala’s H5 Offline Package SDK Boosts Mobile Web Performance

Introduction

Huolala has developed an H5 offline‑package SDK for iOS that dramatically speeds up H5 page loading. The article shows before‑and‑after screenshots of a vehicle‑model page.

The offline package is safe (no hook, no private API, three‑level downgrade), easy to maintain (three‑layer architecture, modular design) and feature‑complete (configurable functions, data‑tracking, developer tools). The source code is open on GitHub.

Background

Web technology is widely used in the Huolala app but suffers from slow loading and poor experience. Existing solutions (Flutter, React Native, mini‑programs, offline packages) have various trade‑offs; offline packages require the least modification and are the most mature.

Industry Solutions

Comparison of common offline‑package approaches:

Load local path – simple and reliable, but has cross‑origin issues.

Request interception – no cross‑origin problem, flexible, but iOS interception APIs are costly.

Local web server – good compatibility, high client CPU/power cost.

Service Worker – good front‑end compatibility, unsupported on iOS WKWebView.

Huolala finally chose the “load local path” scheme.

Technical Implementation

The offline package bundles HTML, JS, CSS, images into a compressed file, downloads it to the device, decompresses it, and loads resources from the local file system, eliminating most network requests.

Key issues and solutions:

CGI cross‑origin – add null‑origin support on the gateway.

Cookie cross‑origin – not used in static JS.

LocalStorage cross‑origin – currently not needed; native calls can solve it.

Absolute‑path support – convert to relative paths.

Overall Flow

On app start the client fetches configuration from a remote server, checks for updates, downloads the package if needed, and WebView loads resources from the local cache when available.

Three update moments:

When the WebView container opens.

At app launch for pages that require real‑time data.

Via long‑connection push for critical updates.

Architecture Improvements

The original two‑layer WebVC caused high integration cost. Huolala refactored to a three‑layer structure separating the base WebVC, the enhanced WebVC and business WebVC, improving maintainability.

Performance Optimizations

Parallel query of multiple offline packages using a shared NSURLSession (HTTP/2 multiplexing).

Download deduplication by using the download URL as a key.

Pre‑download of selected packages at app launch to improve first‑open hit rate.

Breakpoint‑resume download (supported by the internal SDK, not open‑sourced).

Asynchronous, serial decompression to avoid CPU spikes.

Reliability Design

Decompression reliability – decompress to a temporary file then rename to guarantee integrity.

Three‑level downgrade: client‑side fallback, remote configuration fallback, and server‑side fallback.

Benefits

After rollout, average page load time dropped from ~2 s to ~1 s and load success rate increased from 96 % to 100 % for static frames.

Future Work

Open‑source the breakpoint‑resume download SDK and logging SDK, and add more unit tests.

References

GitHub repository, related articles on incremental updates, Service Worker, WKWebView interception, etc.