README
@nrk/nativebridge
Native Bridge is a lightweight and efficient bridge between webview and native app. It's primary use case is to share state between native apps and javascript in webviews.
Support
Tested on Android 4.4.4+ | iOS 10.2+ |
Browser
Used as a producer/consumer-interface for passing messages to/from native app (iOs/Android). Following an EventEmitter
interface (on/once/off/emit). In addition an RPC-interface makes calling native methods a breeze.
EMIT - send to native:
nativebridge.emit('test', { foo: 'bar' }) // Emit 'test' event with data (must be object) to native
ON/ONCE - receives from native:
nativebridge.on('test', (data) => {}) // Bind handler to 'test' event emitted from native
nativebridge.once('test', (data) => {}) // Bind handler to 'test' (one time only) event emitted from native
OFF: - remove handler(s)
nativebridge.off('test') // Unbind all handlers for 'test' event
nativebridge.off('test', (data) => {}) // Unbind specific handler for 'test' event
RPC: - make call to native app using topic as contract
Make a remote procedure call (RPC) using nativebridge interfaces as described above. Resolves with data on completion, or rejects with error details from the app (or timeout).
// Auto-bind handlers (once/emit) to complete an RPC-call to native
nativeBridge.rpc({
topic: 'test', // using 'test' as event
data: {}, // with data (args)
resolve: (data) => {}, // using callback on success
reject: (err) => {}, // or rejection on error
timeout: 1000 // with a timeout threshold
})
Installation
USE WITH NPM:
npm install @nrk/nativebridge --save
import nativebridge from '@nrk/nativebridge'
USE WITH SCRIPT TAG:
<script src="https://static.nrk.no/nativebridge/X.X.X/nativebridge.min.js"></script>
<!-- window.nativebridge is now defined -->
USE WITH REQUIRE.JS:
require(['https://static.nrk.no/nativebridge/X.X.X/nativebridge.min.js'], function(nativebridge) {
/* code here */
});
How does it work
Emit
A data object is sent using topic
as topic to an exposed method on either:
- Android:
window.webkit.messageHandlers.nativebridgeiOS.postMessage({topic: "test", data: {foo: "bar"}})
- iOS:
window.NativeBridgeAndroid.send(JSON.stringify({topic: "test", data: {foo: "bar"}}))
Android/iOS handler
Topic-handlers are mapped to native functions, using data-object as an argument e.g topicHandler({topic: "test", data: {foo: "bar"}})
. The app injects a js-snippet to dispatch a message back to the webpage using CustomEvents:
window.dispatchEvent(new CustomEvent('nativebridge', { detail: {topic, data} }))
On
The CustomEvent dispatched from the native app is ran using attached callback-handlers on the given topic.
Error handling
If an error occurs in the native app, an Error object will be rejected, eg.
err.message = '[{message: "no handler available", errorCode: 100}]'
RPC
The RPC-method is made to simplify on/off/emit-logistics. In addition it supports a timeout, which will throw an error if timeout is reached:
err.message = 'RPC for test using {} timed out after 1000ms'
Local development (web)
First clone @nrk/nativebridge
and install its dependencies:
git clone git@github.com:nrkno/nativebridge.git
cd nativebridge
npm install && npm start
Building and committing
After having applied changes, remember to build before pushing the changes upstream.
git checkout -b feature/my-changes
# update the source code
npm run build
git commit -am "Add my changes"
git push origin feature/my-changes
# then make a PR to the master branch,
# and assign another developer to review your code
NOTE! Please also make sure to keep commits small and clean (that the commit message actually refers to the updated files).
Stylistically, make sure the commit message is Capitalized and starts with a verb in the present tense (for exampleAdd minification support
).