Android Peer-to-peer sync library

Owned by Ephraim Kigamba
Last updated: Jun 19, 2019
3 min read


The Android peer-to-peer sync library is a library/component that enables apps to easily share their records/data with other devices when offline. The library supports 1-to-1 connection and the app can receive record/data updates from another app. This main purpose is to support data reporting up the administration hierarchy after it is collected on the ground where internet connection is scarce but administration has access to internet. It can also be used in many other device-to-device share use-cases


Technologies Used

The library uses a couple of technologies worth mentioning:

  1. Google Nearby Connections API
  2. SQLCipher 4.1.3
  3. Google Mobile Vision API

1. Google Nearby Connections API

Google Nearby Connections API is a peer-to-peer networking API that allows discovery, connection and data exchange in real-time regardless of network connectivity. This library provides the following in the library:

  • Device discovery
  • Device connection
  • Data exchange
  • Connection management

The API uses a combination of Bluetooth, BLE(Bluetooth Low Energy) and Wifi hotspots to perform the functions above. Thus the following technologies are required on the devices for effective and optimal functioning of the library.

Location is required to be turned on and the user requires to accept the Location permissions so that the app can turn this on for you. If location permission is denied, then the library will not be able to work.

2. SQLCipher 4.1.3

This library enables secure storage of transfer history so that updates can be retrieved from other devices.

3. Google Mobile Vision API

This API is provided by Google and provides QR code scanning capabilities on all camera-enabled devices. This capability is required for confirming the connecting device during connection-initiation.

This feature may not work if your Google Play Store application is not up-to-date. In such a case, kindly connect to the internet and try to open the Play Store application on the affected device. This should prompt the Play Store application to update following the required Mobile Vision API.


Purpose

The aim of this library is to provide the following functionality:

  1. Discovery of devices within the same physical location ~ 100 metres
  2. Connection to devices within the same physical location(~ 100 metres) - Both devices have to be in the respective modes i.e. one device has to be in receiving mode and the other device needs to be in sending mode
  3. Initial data exchange between sender and receiver device 
  4. Share data updates from a known sender device to the receiver device - The receiver should only receive updates from the sender device on subsequent data exchanges
  5. Easy integration into any application - The library provides a UI, interfaces and implementation of state management so that the app developer only requires to implement the following:
    1. Authorization conditions between a sending and receiving device
    2. Interface to process received data
    3. Interface to provide the data to be sent based on batch provided
    4. Custom configurations on batch size
    5. Passphrase to be used for the secure database
    6. Username to be used when connecting to peer devices
  6. Data security for share history - The library uses SQLCipher to securely store device identification data that is used to uniquely identifier a device.
  7. Enable authorization conditions between two devices eg, app versions should be similar

Troubleshooting the library

The following are some of the issues and how to fix them:


  1. Why can't the app start receiving or sending mode after clicking on the button?
    • Make sure that the location is turned on. If it is turned on, try turning it off and let the application turn it on
    • Make sure that you accept the location permissions from the prompt displayed
  2. Why does the screen keep on closing after opening it?
    • Make sure that the device has Wifi enabled since it uses the Wifi Mac address as the unique identifier

How to use it in your project


Detailed and updated instructions on how to add it in your Android project can be found here. For use in OpenSRP clients, below is the guide on how to integrate it.


How to use it on OpenSRP Clients


This library has already been integrated into OpenSRP Client Core library and currently supports sharing events, clients and profile images. The default authorization implemented for OpenSRP Client Core makes sure that both the sender and receiver are in the same team by:

  1. Providing the team-id as one of the authorization details
  2. Comparing the team-id of the other device to make sure it matches

To add more authorization conditions, you can override this authorization service or implement your own from interface provided by the library. The authorization service is configurable when setting up the CoreLibrary.

To use the library in an OpenSRP client application,

  1. Import the OpenSRP Client Core library
  2. Add the cwac-saferoom maven repository, as below

    maven {
        url "https://s3.amazonaws.com/repo.commonsware.com"
    }

  3. Add the P2POptions as below when initializing the CoreLibrary:

    1. P2POptions p2POptions = new P2POptions(true);

      // Add the optional configurations to the P2POptions

      p2POptions.setAuthorizationService(new ChwAuthorizationService());

      CoreLibrary.init(context, new ChwSyncConfiguration(), BuildConfig.BUILD_TIMESTAMP, p2pOptions);