sync

The sos.sync API groups together methods for synchronization of multiple devices. Devices are synchronized either through an external server or one of the devices becomes a master device.

Methods

broadcastValue()

The broadcastValue() method sends a key-value pair to all other devices in a specified group.

broadcastValue({ groupName, key, value }: {
    groupName?: string;
    key: string;
    value: any;
}): Promise<void>;

Possible errors

The method throws an error if the value can't be sent

cancelWait()

The cancelWait() method aborts a wait on all devices in a group. Sometimes it's necessary to cancel a pending wait. One such situation would be when the group has to make a sudden change in content or another behavior but there's a risk that part of the group already called wait() and is waiting for the rest but the rest will never call it at this point. In order to gracefully cleanup any pending activity, use this method.

Any pending wait will be canceled and the promise will be rejected with an error.

cancelWait(groupName?: string): Promise<void>;

Example

sos.sync.wait('someData', 'someRandomNameGroup').catch((err) => {
    // this will happend once cancelWait is called
    console.error('wait failed', err);
});

// this will cause above wait promise to reject
await sos.sync.cancelWait('someRandomNameGroup');

close()

The close() method disconnects the device from synchronization server and other devices. Recommended to call this method after the synchronization is not required any longer.

close(): Promise<void>;

connect(options)

The connect() method initializes the device and connects it to the rest of the devices. This initializes the connection and is mandatory to call, since synchronization is an optional feature and doesn’t get initialized by default to save resources and bandwidth. You can optionally specify a custom sync server URI in case you are running the sync server in a custom location.

info

All devices, that should be synchronized together, must select the same engine. Otherwise they won't be able to communicate with each other.

connect(options?: ConnectSyncServerOptions | ConnectP2PLocalOptions | ConnectUdpOptions): Promise<void>;

Params

Name	Type	Description
options.engine	SyncEngine.Udp	Synchronization engine to use.
options.uri (optional)	string	Address of the sync server engine. Only relevant for sync-server. If omitted, the default server will be used.

Possible errors

The method throws an error if unable to connect.

Example

// use default engine
await sos.sync.connect();

// use sync-server engine and default server
await sos.sync.connect({ engine: 'sync-server' });

// use sync-server engine and custom server
await sos.sync.connect({ engine: 'sync-server', uri: syncServerUri });

// use p2p-local engine
await sos.sync.connect({ engine: 'p2p-local' });

isMaster()

Returns true if the device is currently the master of the group.

isMaster(groupName?: string): Promise<boolean>;

Params

Name	Type	Description
groupName (optional)	string	The group name to check for master status. Defaults to the default group.

joinGroup()

The joinGroup() method joins a group of other devices. This method has to be called after connect() call. Before any communication takes place, all participating devices have to be connected and recognize one another. Recommended to call this method early.

joinGroup(options: {
    groupName?: string;
    deviceIdentification?: string;
}): Promise<void>;

Params

Name	Type	Description
options.groupName (optional)	string	By default, all devices will be synced together. To create groups of devices, independent from each other,
specify a group name.
options.deviceIdentification (optional)	string	Identification of a device connected to groupName group.

leaveGroup()

The leaveMethod method leaves a group of devices.

leaveGroup(groupName?: string): Promise<void>;

onClosed()

The onStatus() method sets up a listener, which is called whenever the device is disconnected from the sync. If it closed because close() was called, it will emit without any arguments. if it closed because of an error, it will emit with an error object as the first argument.

onClosed(listener: (error?: Error) => void): void;

onStatus()

The onStatus() method sets up a listener, which is called periodically or whenever there is a change (i.e. new device connects/disconnects to/from the group).

onStatus(listener: (status: StatusEvent) => void): void;

onValue()

The onValue() method sets up a listener, which is called whenever the device receives a broadcasted message.

onValue(listener: (key: string, value: any, groupName?: string) => void): void;

removeEventListeners()

The removeEventListeners() method removes all listeners set up on sos.sync object.

removeEventListeners(): void;

wait()

The wait() method synchronizes with other devices by waiting for other devices before proceeding.

One way to synchronize devices is to make them wait for each other at a certain moment. This would be most commonly used before the device hits “play” on a video, to make it wait for other devices so they all start playing the video at the same time.

This method returns a promise that resolves once all the devices meet and are ready to continue together. Any action that results in visible synchronized behavior should be triggered immediately after and any related background preparations should be called before to prevent delays.

Sometimes devices might go out of sync due to unpredictable conditions like loss of internet connection. To ensure re-sync of an out of sync device, you can pass some data as the first argument. This can be any data that informs the whole group about what content is about to play next. Once all devices are ready, data from the master device is passed to everyone and the rest of the data is ignored. Therefore, when implementing your applet you should rely on the result data and not the data that is passed to the wait method as an argument.

wait(data?: any, groupName?: string, timeout?: number): Promise<any>;

connect(options)

Deprecated

This method was deprecated. Use connect({ engine: 'sync-server' }) instead.

connect(options?: string): Promise<void>;

init()

Deprecated

This method was deprecated. use sos.sync.joinGroup() instead.

init(groupName?: string, deviceIdentification?: string): Promise<void>;

setValue()

Deprecated

This method was deprecated. use sos.sync.broadcastValue() instead.

setValue(key: string, value: any, groupName?: string): Promise<void>;