WebView-Based Offline H5 Implementation and JSBridge Design for Mobile Apps

This article explores how to implement H5 pages with offline‑package capability inside a mobile app using WebView, a topic that may seem outdated but remains valuable for cross‑platform consistency.

Hybrid framework architecture : The solution consists of several modules – a JSBridge for communication, a WebView container, offline resource management, development debugging tools, an offline‑package management backend, server‑side services, a package protocol, and stability/security mechanisms.

Communication schemes (JS → Native) : Various methods are discussed, including fake URL schemes, alert/confirm/prompt interception, JSContext injection, Android addJavascriptInterface , and iOS WKWebView MessageHandler. Example code snippets:

const url = 'https://qq.com/xxx?param=xxx';
const fakeUrl = 'scheme://getUserInfo/action?param=xx&callbackid=xx';

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url) {
    // 1. Check URL scheme/domain
    if (/* is our scheme */) {
        // 2. Extract path, 3. Extract parameters, 4. Call native method
        return true;
    }
    return super.shouldOverrideUrlLoading(view, url);
}

- (void)webView:(WKWebView *)webView decidePolicyForNavigationAction:(WKNavigationAction *)navigationAction decisionHandler:(void (^)(WKNavigationActionPolicy))decisionHandler {
    // 1. Check URL scheme/domain
    if (/* is our scheme */) {
        // 2‑4. Extract path, parameters, invoke native logic
        decisionHandler(WKNavigationActionPolicyCancel);
    } else {
        decisionHandler(WKNavigationActionPolicyAllow);
    }
    return YES;
}

Prompt‑based communication (synchronous) is also shown:

const ret = prompt(jsonData);

Communication schemes (Native → JS) : Native code can execute JavaScript directly. iOS uses evaluateJavaScript , Android uses evaluateJavaScript (API ≥4.4) or loadUrl("javascript:calljs('…')") for older versions.

window.webkit.messageHandlers.nativeObject.postMessage(data);

JSBridge SDK design : A platform‑agnostic JavaScript SDK abstracts the underlying native calls. Core features include invoke , invokeSync , callback handling, and Promise‑based APIs such as getSystemInfo . Example SDK skeleton:

class BridgeNameSpace {
  invoke = (eventName, params, callback) => {
    // generate callbackId, store callback, call native
  };
  invokeSync(eventName, params, callback) {
    // similar to invoke but returns result synchronously on iOS
  }
  invokeCallbackHandler = (id, params) => {
    const fn = this.invokeMap.get(id);
    if (typeof fn === 'function') fn(params);
    this.invokeMap.delete(id);
  };
  getSystemInfo(callback) {
    return new Promise((resolve, reject) => {
      this.invoke('getSystemInfo', {}, res => {
        res.status === 'success' ? resolve(res) : reject(res);
      });
    }).then(callback).catch(callback);
  }
}
window.BridgeNameSpace = new BridgeNameSpace();

Typical usage:

BridgeNameSpace.getSystemInfo().then(res => console.log(res)).catch(err => console.log(err));
BridgeNameSpace.getSystemInfo(res => console.log(res));

Scenarios : (1) Query device info from JS; (2) Subscribe to page‑visibility events; (3) Communicate between two WebViews via native mediation using notify and subscribeNotify methods.

BridgeNameSpace.subscribeNotify('QSOverlayPlayerBackClick', res => console.log(res));
BridgeNameSpace.notify('QSOverlayPlayerBackClick', {test: 'a'}, res => console.log('notify success'));

Offline package construction : An offline package follows a defined protocol – it must contain page-frame.html , a config.json file, and all static assets (js, css, img). Example ZIP layout:

zip
└── page-frame.html
├── config.json
├── css/main.f855e6bc.css
├── js/787.d4aba7ab.chunk.js
├── js/main.8381e2a9.js
└── img/arrow.80454996.svg

The config.json defines global and per‑page settings such as navigation‑bar visibility and theme colors:

{
  "global": {
    "showNavigationBar": false,
    "themes": {
      "black": {"backgroundColor": "#0a0c0e"},
      "white": {"backgroundColor": "#FFFFFF"}
    }
  },
  "pages": {
    "index": {"showNavigationBar": false},
    "detail": {"showNavigationBar": true, "themes": {}}
  }
}

Offline‑package management : Each package version records pid , verify_code , pkg_md5 , gray_rule , pkg_url , required SDK version, status, and metadata. The app fetches a configuration table at launch or periodically, pre‑downloads high‑priority packages, and falls back to online resources when a package is missing or fails verification (domain whitelist, MD5, verify_code).

Container basic capabilities : Native UI components (toast, loading bar) and embedded native features (header, share panel, pull‑to‑refresh) are exposed via the SDK:

showToast(position, text, callback) { this.invoke('showToast', {position, text}, callback); }
loadingBar(action, callback) { this.invoke('loadingBar', {action}, callback); }

Header configuration example:

setHeaderConfig(config, callback) {
  this.invoke('setHeaderConfig', {
    title: config.title,
    subTitle: config.subTitle,
    right: [{actionName: 'font'}, {actionName: 'share', icon: ''}]
  }, callback);
}

Pull‑to‑refresh API:

enablePullDownRefresh(enabled, callback) { this.invoke('enablePullDownRefresh', {enabled}, callback); }
startPullDownRefresh(callback) { this.invoke('startPullDownRefresh', {}, callback); }
stopPullDownRefresh(callback) { this.invoke('stopPullDownRefresh', {}, callback); }
onPullDownRefresh(callback) { this.on('onPullDownRefresh', callback); }

Development & debugging : Local development uses QR‑code scanning or manual URL entry on a real device, enabling hot‑reload. Online updates rely on the offline‑package platform with separate test and production environments; the app determines its environment via JSBridge and fetches the appropriate package URLs.

Stability & security : The framework includes resource integrity checks (MD5), domain whitelisting, and graceful fallback strategies for each critical step (download, unzip, load, render). Secure containers can restrict unsafe APIs for sensitive scenarios (e.g., finance).

In conclusion, the article provides a comprehensive guide to designing a hybrid WebView solution with offline capabilities, a robust JSBridge SDK, and practical considerations for packaging, versioning, debugging, and security.