cordova-plugin-bridgefy

Cordova Bridgefy Plugin

Usage no npm install needed!

<script type="module">
  import cordovaPluginBridgefy from 'https://cdn.skypack.dev/cordova-plugin-bridgefy';
</script>

README

cordova-plugin-bridgefy

This plugin allows the client to transmit data to nearby peers without the necessity of an Internet connection or an access point. It also implements a mesh-network transmission algorithm that enables devices to send data to peers that are so far away that they aren't visible to the client device.

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log(bridgefy.version);
}

Installation

cordova plugin add cordova-plugin-bridgefy

Supported Platforms

  • Android
  • iOS

Android Quirks

This guide will show you the necessary steps to start using the Bridgefy SDK on your app. The first step is to generate an API key at http://bridgefy.me

Added AndroidX Support

Bridgefy requires AndroidX support, you can enable this feature by setting the AndroidXEnabled preference to true in config.xml.

<preference name="AndroidXEnabled" value="true" />

App Requirements

The Bridgefy SDK supports Android 5.0 (API Level 21) or higher and the following permissions are required:

android.permission.BLUETOOTH
android.permission.BLUETOOTH_ADMIN
android.permission.INTERNET

Internet access is required during the first run in order to check for a valid license in our servers.

If you're targeting devices with Android 6.0 (API Level 23) or higher, either one of the following permissions is also required:

android.permission.ACCESS_FINE_LOCATION

android.permission.ACCESS_COARSE_LOCATION

Note.- Devices with Android 6.0 (API Level 23) or higher also need to have Location Services enabled

Hardware requirements

This version is fine-tuned for Bluetooth Low Energy (BLE) capable devices. While it is not required, it is preferable that the BLE advertising mode is also supported. The Bridgefy SDK will let you know during initialization if your devices support BLE advertising or not. At least one device should support advertising mode in order for connections and, thus, messaging functionality, to be successful.

iOS Quirks

Go to your Bridgefy Dashboard, then go to your Licence List and download the .txt file inside, which contains a String.

Dashboard licence

Copy the certificate string that was generated along with your app's API Key.

In info.plist, create an entry named com.bridgefy.SDKLicense and paste the text value. If there is no Internet connection available, the Transmitter Framework will use this certificate to validate your licence.

Dashboard licence

Setting Permissions

We need to define a value for the NSBluetoothAlwaysUsageDescription key if using iOS13 or NSBluetoothPeripheralUsageDescription if using iOS12 or earlier. This is the message that is displayed to the user when asking for Bluetooth permission for the app. If we are designing for apps to be used on phones with iOS13 and previous versions as well then it makes sense to define values for both of these keys. This needs to be done in the Info.plist file.

Permissions

Methods

  • bridgefy.version
  • bridgefy.init
  • bridgefy.start
  • bridgefy.stop
  • bridgefy.deviceListener
  • bridgefy.messageListener
  • bridgefy.sendMessage
  • bridgefy.sendBroadcastMessage

bridgefy.cordova

Get the version of Cordova running on the device.

bridgefy.init

The Bridgefy Plugin needs only a call to the bridgefy.init in order to create all required objects and to be ready to start operations.

Quick Example

// Function successCallback The function to call when the heading data is available
// Function errorCallback The function to call when there is an error getting the heading data.
// ApiKey (Required) generate an API key at https://bridgefy.me
//
                
bridgefy.init( 
    (response) => { // successCallback
            console.log('Bridgefy client: ' + JSON.stringify(response));
        }, 
    (e) => { // errorCallback
        console.error(e);
        }, 
        'YOUR_API_KEY');

bridgefy.start

Before you start, you must assign listeners that will report the events of nearby devices and the events of sending packages. Once the Bridgefy SDK has been correctly registered we are now ready to start the Bridgefy SDK. Use the following method to begin the process of nearby devices discovery as well as to advertise presence to other devices.

// Function successCallback The function to call when the heading data is available
// Function errorCallback The function to call when there is an error getting the heading data.
// You can also provide a custom Config object to set additional options 
bridgefy.start(successCallback, errorCallback, options);

Bridgefy SDK options, for more details, see Bridgefy Options - only android

Quick Example

// Add Device Listener
bridgefy.deviceListener(successCallback, errorCallback);
// Add Message Listener
bridgefy.messageListener(successCallback, errorCallback);

// Start operations
let options = bridgefy.config;
    options.autoConnect = true; // tells Bridgefy if we want Automatic on On-demand mode
    options.encryption = true; // All communicaiton is secure
    options.energyProfile = 'HIGH_PERFORMANCE'; // Android only, see https://github.com/bridgefy/bridgefy-android-samples#engine-profile
    options.engineProfile = 'BFConfigProfileLongReach'; // Android only, see https://github.com/bridgefy/bridgefy-android-samples#energy-profile

bridgefy.start(
    () => {     //   successCallback
                //   Your code
    }, (e)=> {  //   errorCallback
        console.log('Bridgefy error ', JSON.stringify(e));
    },
    options);   //   Options configured

bridgefy.stop

Once you've ready to start the plug-in, always make sure to stop the Bridgefy instance in order to free up device resources.

// Function successCallback The function to call when the stop bridgefy successfully
// Function errorCallback The function to call when there is an error to stop bridgefy.
bridgefy.stop(successCallback, errorCallback);

Quick Example

// Strop bridgefy
bridgefy.stop(
    () => {
        // Your code
    }, (e) => {
        console.error(e);
    });

Automatic and On-demand modes

You can use Bridgefy in two different modes: "Automatic" and "On-demand".

More information about those modes for iOS and Android.

Automatic mode

When using Bridgefy in Automatic mode, you do not have to manage connecting to users, it is done automatically for you by the Bridgefy SDK.

Each time a user will be connected to you, the onDeviceConnected event will be thown along with the user information.

Similarly, the onDeviceLost event will be raised every time a user disconnects from you.

On-demand mode

In the On-demand mode, you will have to connect to other devices once you've detected them. You know when a device is detected when the onDeviceDetected event is raised (along with the device information).

When a device is detected, you can call the connectDevice function to connect it and be then able to send messages to it:


bridgefy.connectDevice(
        (resp) => { },  // --> Success Callback 
        (e)=> { },      // --> Error Callback
        device.userId); // --> User ID

If you want to disconnect from a device, you call:

bridgefy.disconnectDevice(
        (resp) => { },  // --> Success Callback 
        (e)=> { },      // --> Error Callback
        device.userId); // --> User ID

You know when you are connected to a device when the onDeviceConnected event is raised (similarly to the automatic mode). You also know when you are disconnected from a device when the onDeviceLost event is raised.

When a device becomes unavailable (un-detected), the onDeviceUnavailable event is raised along with the device information.

bridgefy.deviceListener

When a peer is detected, the connection is made automatically. The following successCallback is invoked when a peer has established connection:

bridgefy.deviceListener(successCallback, errorCallback);

Response description

  • action:
    • connected
    • disconnected
    • detected
    • unavailable
  • device
    • userId (UUID) *in iOS this attribute only
    • deviceAddress
    • sessionId
    • antennaType
    • deviceName

Quick Example

//
// Function successCallback The function to call when exist a event.
// Function errorCallback The function to call when there is an error.
//
bridgefy.deviceListener((response) => {
    // response has a action and device
    // response = {
    //  action: "STATUS", -> Must be "connected" or "disconnected"
    //  device: Object
    // }
    console.log(JSON.stringify(response));
}, (e) => {
    console.error(e);
});

bridgefy.messageListener

When a packet has been received, the following method will be invoked:

bridgefy.messageListener(successCallback, errorCallback);

Response description

  • action:

    • incoming_message
    • incoming_message_broadcast
    • message_sent
    • message_error

  • message

    • senderId - current client UUID
    • receiverId - receiver UUID
    • data - binary data of message
    • hop - maximum number of jumps
    • hops - hops in the mesh network
    • dateSent - date time sample: 1575654108172
    • uuid - message UUID
    • content - received dictionary
    • progress - progress 0 to fullSize
    • fullSize - outgoing binary data size

Quick Example


bridgefy.messageListener((response) => { // successCallback
    console.log('Receive message event: ' + response.action);
    console.log('Receive message content: ' + JSON.stringify(response.message));
}, (e) => { // errorCallback
    console.error(e);
});

bridgefy.sendMessage

The following method is used to send data to another peer. This method performs an initial validation over the received parameters, and if everything is correct, generates a packet identifier that is returned to the client. All of this initial process is synchronous. After this, the packet enters to an asynchronous process for the transmission of the packet.

You can send messages to other devices even if they haven't been reported as connected or in-range. The Bridgefy SDK will do its best effort to deliver the message to its recipient through intermediate devices. Message content is secured through a 256-bit encryption which is managed seamlessly for you so you don't have to worry about other users tapping into your private messages.

bridgefy.sendMessage(successCallback, errorCallback, device, message);

Parameters

  • Function successCallback(uuid)
  • Function errorCallback(error)
  • Object device
  • Objacet message

Quick Example

bridgefy.sendMessage(
                    (res)=>{    // Success Callback
                        console.log('Message sent: ' + res)
                    }, (e)=> { // Error Callback
                        console.error('Error to send message: ', e);
                    },
                    deviceDetected, // Sent to device
                    { message: 'Test' }); // Message

bridgefy.sendBroadcastMessage

You can also send public messages which will be propagated to all nearby devices. Those are even easier to send:

bridgefy.sendBroadcastMessage(successCallback, errorCallback, message);

Parameters

  • Function successCallback(uuid)
  • Function errorCallback(error)
  • Objacet message

Quick Example

bridgefy.sendBroadcastMessage(
                    (res)=>{    // Success Callback
                        console.log('Message sent: ' + res)
                    }, (e)=> { // Error Callback
                        console.error('Error to send message: ', e);
                    },
                    { message: 'Test' }); // Message

Documentation

Contact

  • contact@bridgefy.me