PhotonSync

Version compatibility

• PhotonSync was introduced in version 4.59.0 of the JourneyApps Container.

• PhotonSync is currently only available for customers on the Enterprise plan.

JourneyApps supports offline data transmission between devices. This is achieved by using flashing QR Codes in a component called PhotonSync.

How to check if PhotonSync is supported

If users are using versions below 4.59.0, you will have to check that the PhotonSync object is available:

main.js

    if(PhotonSync) {
        // use PhotonSync here
    }

Some devices may not be able to receive or transmit data. To check this, call:

main.js

    var capabilities = PhotonSync.getCapabilities();

This returns:

    {
        transmit: true|false,
        receive: true|false
    }

Typical use case

PhotonSync is intended to copy data between users who are not necessarily connected to a network. An example is a user who has captured data in the field, and wants to share it with a colleague in a remote area. Typically, the data would be exported and copied to an external device and imported by the other user.

This takes a lot of time, and the user could forget to remove the data from the external device.

With PhotonSync, the user with the data will have flashing QR Codes on their screen. The user that wants to receive the data will point their device with a camera to the flashing QR Codes until the progress bar is full. They will then have the intended data.

PhotonSync can be thought of as a pipe between the two users. This means that the format of the data is completely in the hands of the developer, and they have to check the data format received for errors etc.

Sending data

PhotonSync is capable of sending any text or ArrayBuffer data. If your data is an object, you will have to convert it to text first, using e.g. JSON.stringify() or converting it to a CSV string.

To send, use:

main.js

PhotonSync.transmit(data, options);

where optional options:

value	Details	Default
compressText	Compresses text to transmit text faster	true
color	Color of the QR Code. Can be a named color, e.g. "primary". or hex value, e.g. "#123456"	black
FPS	Frames Per Second. The maximum number of codes to flash per second	5
packetSize	Size of pieces of the data when splitting in bytes. E.g. 400	Depends on the screen of the sender, but typically 500 on small devices and 1200 on larger devices. Do not go higher than 1200.

Receiving data

To receive data, use:

var received = PhotonSync.receive(options);
if(received) {
    // use data
} else {
    // cancelled or error
}

where optional options:

value	Details	Default
type	Type of the data to receive. Can be "utf8", "arraybuffer", "uint8array" or "base64"	"utf8
progressColor	Color of the progress bar. Can be a named color, e.g. "primary". or hex value, e.g. "#123456"	"primary"

Example

Consider the use case where we want to transmit some “valve” objects from one user to another. We would have a sendValves function that can be triggered from a button etc:

function sendValves() {
    var valvesArray = LocalDB.valve.all().toArray();
    var jsonToTransmit = JSON.stringify(valvesArray);
    PhotonSync.transmit(jsonToTransmit);
}

On the receiver, we would have a receiveValves function:

function receiveValves() {
    LocalDB.valve.where('original = ?', false).destroyAll();

    var received = PhotonSync.receive();
    if(received) {
        var receivedArray = JSON.parse(received);
        receivedArray.forEach(function(r) {
           var newValve = LocalDB.valve.create();
           newValve.serial = r.serial;
           newValve.size = r.size;
           newValve.health = r.health;
           newValve.age = r.age;
           newValve.original = false;
           newValve.save();
        });
        view.receivedValves = LocalDB.valve.where('original = ?', false).orderBy('serial');
    }
}

Note: Since this data was copied from the one device to the other, the developer has to keep track of which data is the copy and which is the original. In this example, the model for the valve has an explicit “original” field:

schema.xml

<model name="valve" label="Valve">
    <field name="serial" label="Serial" type="text" />
    <field name="size" label="Size" type="text" />
    <field name="age" label="Age" type="number" />
    <field name="health" label="Health" type="text" />
    <field name="original" label="Original" type="boolean" />
    <display>Valve: {serial}</display>
</model>

Keeping track of this is up to the developer, so other options can be used. Just remember that not keeping track of this may lead to duplicate models in the backend that will have different id’s, but the same data.

Usage notes

• Unfortunately, Android devices are not able to receive data, yet. Android may be supported for receiving soon, so ensure that PhotonSync.getCapabilities() is checked before using it.

• Currently, PhotonSync cannot copy attachments, like photos or signatures, though this may change in the future.

• The speed that PhotonSync is able to copy data at is non-deterministic and depends on many factors. With internal tests, which should be representative of good conditions, we were able to copy 1000 database objects in five seconds.