@spindox/cordova-venice-bridge

Cordova <=> Venice bridge

This library is been created to make Cordova plugins work inside an iframe.
Two actors are needed in the game: a host Cordova application and a guest web application.
The bridge has an implementation for each of them.

Requirements

Platforms

• cordova-android min version: 6.3.0 - max version: 7.1.0
• cordova-ios version: 4.5.4

Plugins

• cordova-plugin-device min version: 1.1.6 - max version: 2.0.1
• cordova-plugin-inappbrowser version: 2.0.2
• cordova-plugin-qrscanner version: 2.5.0
• cordova-plugin-shake version: 0.6.0
• cordova-plugin-keyboard version: 1.2.0
• cordova-plugin-geolocation version: 2.4.3
• uk.co.workingedge.phonegap.plugin.launchnavigator version: 4.0.5

For each item of the list above there is a Venice topic that has one-to-one API implementation.

The only exception is uk.co.workingedge.phonegap.plugin.launchnavigator: the navigate API is the only one implemented by the bridge.

Installation

npm install --save @spindox/cordova-venice-bridge

Host

The Cordova application that want to include another application inside an iframe can use the object host exposed by the bridge.

API

• connect
• disconnect

host.connect(iframe, options, onReady)

Connects a side of the bridge (the host) and registers Cordova plugins by subscribing a Venice channel for each plugin listed above.
Call this method in the onLoad handler of the iframe or wherever the iframe is ready.

Parameter	Type	Description
iframe	HTMLIFrameElement	The instance of the iframe that contains the guest application
options	Object	Optional. Configuration options
options.log	boolean	Enables or disables logs (default: false)
onReady	function	Optional. The callback invoked when the other side of the bridge (the guest) is ready

Example

import cordovaBridge from '@spindox/cordova-venice-bridge';

function handleIframeOnLoad() {
  const iframe = document.querySelector('iframe');
  const options = {
    log: process.env.BUILD_ENV === 'development',
  };
  
  cordovaBridge.host.connect(iframe, options);
}

host.disconnect()

Disconnects a side of the bridge (the host) and unregisters all cordova plugins.
Call this method when you remove the iframe from the DOM or whenever you want to interrupt the bridge comunication.

Example

import cordovaBridge from '@spindox/cordova-venice-bridge';

function disconnectCordovaBridge() {  
  cordovaBridge.host.disconnect();
}

Guest

The application that lives in the iframe can use the object guest exposed by the bridge.

API

• connect

• disconnect

• Cordova plugins bridge

guest.connect(options, onReady)

Connects the other side of the bridge (the guest).
Call this method at the startup of the application.

When the connection between the both side of the bridge is ready, the guest application asks to the host the information about Cordova plugins and save all in the global object cordovaBridge that will be available in window.
For each Cordova plugin listed above there will be an object like this:

device: {
  id: 'cordova-plugin-device',
  name: 'device',
  available: true,
  data: {...}, // optional
},

Parameter	Type	Description
options	Object	Optional. Configuration options
options.log	boolean	Enables or disables logs (default: false)
onReady	function	Optional. The callback invoked when the other side of the bridge (the host) is ready

Example

import cordovaBridge from '@spindox/cordova-venice-bridge';

function setupGuestMode() {
  const options = {
    log: process.env.BUILD_ENV === 'development',
  };
  
  cordovaBridge.guest.connect(options);
}

guest.disconnect()

Disconnects the other side of the bridge (the guest).

Example

import cordovaBridge from '@spindox/cordova-venice-bridge';

function disconnectCordovaBridge() {  
  cordovaBridge.guest.disconnect();
}

Cordova plugins bridge

For each Cordova plugin reimplemented by this library, there is a bridge available for the guest application.

Each bridge (except for uk.co.workingedge.phonegap.plugin.launchnavigator) exposes the same API of the original plugin (at the version specified in the requirements) and, in addition, a method isAvailable() to check the plugin availability.

Example

import shakeBridge from '@spindox/cordova-venice-bridge/guest/cordova-plugin-shake';

function connectShakeBridge() {
  const shakeIsAvailable = shakeBridge.isAvailable();
  if (!shakeIsAvailable) return;
  
  shakeBridge.startWatch(() => { // handler goes here });
}

function disconnectShakeBridge() {
  const shakeIsAvailable = shakeBridge.isAvailable();
  if (!shakeIsAvailable) return;
  
  shakeBridge.stopWatch();
}

##Licence: MPL2.0 This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.