Hybrid App Architecture and JSBridge Implementation Overview

With the rapid development of web technologies and mobile devices, hybrid solutions have become the most mainstream approach for building apps. A well‑designed hybrid architecture enables an app to deliver native‑level experience and performance while retaining the flexibility, cross‑platform capability, and hot‑update mechanisms of web development.

Existing Hybrid Solutions

WebView UI based solution – used by many mainstream apps (e.g., WeChat JS‑SDK) where a JSBridge provides two‑way communication between H5 and native, granting limited native capabilities to the web page.

Native UI based solution – such as React‑Native and Weex. H5 code is parsed into a virtual DOM, which is then rendered by native components via a JSBridge.

Mini‑program solution – a more customized JSBridge that uses a dual‑WebView, dual‑thread model to isolate JS logic from UI rendering, further increasing the hybrid degree.

All three schemes rely on a JSBridge communication layer. The second and third schemes can be seen as extensions of the first, adding more sophisticated native integration.

Scheme Selection

Rapid iteration and flexible development of web technologies with hot‑update mechanisms.

Strong photo and image‑processing capabilities are core to the product, requiring native support beyond pure H5.

The existing native UI components are mature, so a full React‑Native approach is unnecessary.

Thus, the goal is to combine the rapid development of H5 with native performance and reuse existing native components.

Hybrid Technology Principle

The essence of a Hybrid App is embedding a WebView in a native container, making the bidirectional communication (JSBridge) between Native and H5 the core component. This communication can be viewed as a cross‑language bridge between Native (Java/Objective‑C/…) and JavaScript.

4.1 JavaScript Notifying Native

Three common approaches:

API injection – Native injects an object or method into the JavaScript context, allowing direct calls from JS.

Prompt/console/alert interception – usually using prompt because it is rarely used in normal front‑end code.

WebView URL Scheme interception – intercepting custom scheme URLs.

The third method is detailed below.

4.1.2 Protocol Customization

A custom URL scheme is defined, e.g.:

xxcommand://xxxx?param1=1&param2=2

Key points:

The scheme can be tailored to business needs, e.g., xxcommand:// as a universal protocol for all apps, and xxapp:// for app‑specific commands.

Do not use location.href for sending because concurrent requests may be merged; instead, create an iframe to trigger the request.

For security, set a domain whitelist on the client side to prevent unauthorized third‑party calls.

4.1.3 Protocol Interception

Clients intercept requests via platform APIs:

iOS: shouldStartLoadWithRequest

Android: shouldOverrideUrlLoading

When a request matches the custom scheme, the client parses parameters and invokes the corresponding native functionality instead of loading a resource.

4.1.4 Protocol Callback

Since the request is asynchronous, callbacks are handled using the JavaScript event system:

Register a custom event with a unique identifier using window.addEventListener and trigger it from native with window.dispatchEvent .

Example flow:

Send a protocol request and register a custom event for the response.

Native processes the request and calls dispatchEvent with the result.

Developers should avoid multiple bindings; when a unique identifier is reused, remove the previous listener with removeEventListener .

4.2 Native Notifying JavaScript

Native can execute JavaScript directly via WebView APIs:

iOS: stringByEvaluatingJavaScriptFromString

Android (pre‑4.4): loadUrl

Android (4.4+): evaluateJavascript

For Android versions below 4.4, evaluateJavascript is unavailable, so the prompt method is used for data exchange.

With these mechanisms, the basic JSBridge for bidirectional communication is established.

4.3 JSBridge Integration

The implementation consists of two parts:

JS part (bridge) : injected into the HTML head, handling protocol assembly, sending, parameter pool, and callback pool.

Native part (SDK) : client‑side code that intercepts URLs, injects environment info, and maps generic functions.

Both parts are packaged into a native SDK. When a WebView loads a whitelisted page, the SDK automatically injects bridge.js into the HTML head.

Benefits:

Unified code maintenance avoids version fragmentation.

Easy integration: update the SDK once to propagate changes to all apps.

H5 developers do not need to manage the bridge, enabling third‑party page usage.

Note: The bridge must be injected before any protocol calls. Since injection is asynchronous, H5 should listen for a custom event such as:

window.addEventListener('bridgeReady', e => {})

4.4 H5 Integration Methods in Apps

Two common approaches:

Online H5 – host the H5 code on a server and load it via URL in a WebView. Advantages: strong independence, no impact on app size, low integration cost, hot‑update friendly. Disadvantages: requires network, slower first‑screen load on slow connections.

Embedded H5 – package the H5 code into the app bundle and load it locally. Advantages: fast first‑screen load, offline capability. Disadvantages: more complex development and update workflow, increases app package size.

Selection should be based on the specific scenario.

Conclusion

This article analyzed the current state and fundamentals of Hybrid Apps, covering:

JavaScript notifying Native

Native notifying JavaScript

JSBridge integration

H5 integration methods

Understanding these core principles is essential before implementing and optimizing a hybrid solution.