Building a Hybrid App Bridge: Architecture, Implementation, and Protocol Design

This article continues the series on Hybrid app architecture by moving from theory to practice. It demonstrates how to implement a complete and stable Hybrid solution using a custom bridge.js that enables communication between the Native side and H5 pages.

Project Overview

The showcased Hybrid module is fully embedded in an app, consisting of four pages: two H5 pages (home and creation) and two Native pages (camera and save). The module has been live for a year with over 1 billion uses, proving its robustness.

Why a Bridge?

The bridge is needed for:

Frequent UI style updates.

Dynamic business logic requiring hot updates.

Reusing existing Native camera and save pages.

Integrating multiple SDKs (e.g., image‑processing algorithms).

Bridge.js Architecture

The core of the bridge is the nativeCall flow, which follows four steps:

Generate a unique handler identifier.

Store parameters in a parameter pool ( _paramsStore ).

Register a custom event with the handler and store the callback in _callbackStore using addEvent() .

Send the protocol via an iframe using send() .

On the Native side, the received handler is used to retrieve parameters with getParam , execute the requested function, and then call Bridge.postMessage(handler, data) to return the result to H5.

Android Compatibility

For Android versions below 4.4, loadUrl cannot return a value, so the article proposes using the WebView prompt interception technique. The flow is:

Native receives the protocol and extracts the handler.

Execute Bridge.getParam(handler) via loadUrl .

Intercept the prompt in onJsPrompt to obtain the parameter.

This method works uniformly across all Android platforms.

Protocol Customization

After establishing the basic bridge, the article defines two categories of protocols:

Functional protocols (e.g., _init_ , _resume_ , addEvent , fireEvent , send ) that provide generic capabilities for any project.

Business protocols that encapsulate project‑specific logic such as image‑processing or custom navigation.

Examples of functional protocols include:

nativeCall / postMessage for bidirectional calls.

getParam for retrieving stored parameters.

addEvent and fireEvent for event handling.

send for sending commands via iframe.

Environment & Localization

The bridge can pass environment information ( data.env ) and language settings ( e.data.language ) during the _init_ event, allowing H5 to adapt to production, testing, or development environments.

Event Hub

An event hub ( _eventListeners_ ) is introduced to listen for hardware back‑button events on Android, ensuring proper navigation when H5 pages display dialogs or SPA transitions.

Data Transfer Mechanism

To keep Native and H5 data synchronized, a set of data‑transfer protocols is defined, enabling seamless state sharing.

Proxy Requests

Because H5 faces cross‑origin, encryption, and authentication challenges, the article proposes four proxy protocols handled by the Native side:

getProxy / postProxy

getProxyLogined / postProxyLogined (automatically attach user token and UID).

These proxies simplify H5 code and provide a unified request entry point.

Additional Functional APIs

getNetwork – obtain network status.

openApp – launch other apps.

setShareInfo / callShare – share content.

link – open a new WebView.

closeWebview – close the current WebView.

setStorage / getStorage – manage local cache.

loading – control a global loading indicator.

setWebviewTitle – set the WebView title.

saveImage – save images to the device.

All these APIs are designed to be pure, reusable building blocks that can be maintained as a common SDK, while business‑specific protocols remain project‑specific.

Conclusion

The article wraps up the front‑end part of the Hybrid solution, providing a solid foundation for developers to start building their own Hybrid modules. Future posts will address optimization and deeper engineering challenges.