Skip to content
Web2Native Bridge emulator for Chrome and Firefox (Desktop)
JavaScript Java C++ Shell HTML Batchfile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Web2Native Bridge - Uniting the "Web" and "App" worlds

Note: this is a system in development, the specification may change anytime without notice

This repository contains all code for building and testing an emulation of the Web2Native Bridge concept ( using the Google Chrome and Mozilla Firefox desktop browsers. It also runs on the Open Source Chromium browser.

The emulator code exploits Chrome's native messaging ( featured in a single universal Chrome/Firefox extension.

Applications callable by the Web2Native Bridge emulator must be written in Java and stored in a for the purpose dedicated directory.


The Web2Native Bridge emulator extends the navigator object by a single method
nativeConnect('Name of target application' [, optionalArgument]) which returns a JavaScript Promise to a port object.

The port object supports the following methods and events:

  • postMessage(message)
  • disconnect()
  • addMessageListener(function(message))
  • addDisconnectListener(function())

optionalArgument and message must be valid JSON-serializable JavaScript objects.

An example which could be hosted in an ordinary (non-privileged) web page:

navigator.nativeConnect('com.example.myapp').then(function(port) {

    port.addMessageListener(function(message) {
        // We got a message from the native application...

    port.addDisconnectListener(function() {
        // Native application disconnected...

    port.postMessage({greeting:'Native app, how are you doing?'});
    // Note: JavaScript serialization makes the above a genuine JSON object

    port.disonnect();  // Not much of a conversation going on here...

}, function(err) {

The argument to nativeConnect holds the name of the specifically adapted local application to invoke. The current scheme uses a Java-inspired dotted path pointing to a subdirectory and JAR-application having this name.


For specifying access to native applications there must be a JSON-formatted manifest file associated with each application. The following manifest provides universal access to an application:

  "callableFrom": ["*://*/*", "file:///*"]

A more restrictive manifest could limit access to a single domain and https operation:

  "callableFrom": ["*", "https://**"]


The Web2Native Bridge emulator always invokes a central proxy located at proxy/install/w2nb-proxy.

The proxy in turn dispatches a call to the specific target application located at

The mandatory manifest file is stored at

Common Java libraries may be stored in proxy/install/libs.

For debugging purposes there is also a logging system writing data in proxy/install/logs.

All local I/O between the browser, proxy and the callable applications is performed through stdin and stdout.

Native Application Interface

Native applications (in the prototype Java applications hosted in JAR-files) are called as follows:

args[0]Absolute path to the proxy/install directory
args[1]Application name (dotted path)
args[2]URL of calling web page
args[3]Coordinates of calling web page
args[4]Custom invocation data (OptionalArgument)
args[5...]Chrome's Native Messaging arguments
For detailed information about the format of these fields, turn to the code :-)



  • You need to have Java SE version 8 installed to run the Web2Native Bridge emulator
  • OS/X and Linux installations presume that clang respectively g++ is available
  • Clone the web2native-bridge master repository or just download the ZIP via GitHub to any free directory

Note: If you are using Oracle Java you must install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files as well.

Chrome/Chromium specific steps

  1. Start a terminal window and move to proxy/install. Then run the install-proxy script that suits your platform
  2. Install the Web2Native Bridge browser extension from the Chrome Web Store:
  3. In Chrome, go to Settings->Extensions and check "Allow access to file URLs" for the Web2Native Bridge extension

Firefox specific steps

  1. Start a terminal window and move to firefox/install. Then run the install-proxy script that suits your platform
  2. Install the Web2Native Bridge browser extension from the file firefox/install/xpi/web2native_bridge_emulator-1.0.xpi using the Firefox menu option: Add-ons->Extensions->Install Add-on from file.

Testing the installation

Now you can try the two sample applications (see next sections) since they are installed by default.

Please don't hesitate contacting me if you run into problems during installation or execution of the emulator!

Basic Sample Application

The HTML file sample1/demo/sample1.html does approximately the same thing as the application depicted in albeit with a few significant enhancements:

  • The sample application is invoked by an ordinary web page
  • The Web2Native Bridge browser extension is fully generic and can support any number of very different applications
  • The Web2Native Bridge adds positioning support enabling alignment UI-wise with the web

The native part of the sample application resides in proxy/install/apps/org.webpki.w2nb.sample1/org.webpki.w2nb.sample1.jar.

Single Page Application

Although not a design goal, the Web2Native Bridge API is also compliant with the SPA concept:

Security Considerations

Since an emulator by definition isn't the "real thing" some limitations apply. That is, the Web2Native Bridge emulator is not intended for production since it doesn't support the following security measures:

  • Native application vetting infrastructure. An improperly designed native message extension could enable web access to the entire computer!
  • HTTPS information
  • Site-blocking support and associated administration

Although not entirely comforting, Chrome's native messaging framework also lacks these qualities...

In addition, the scheme injects code in every web page visited which is a core "feature" of Chrome extensions slowing down execution. It is probably wise disabling the extension (using Chrome settings) when not using it.

You can’t perform that action at this time.