About Api

Each of the module APIs has a similar structure. Modules provides API which is divided into 3 parts:

• actions - functions that client can call to manipulate data or send requests to server,
• data - provides collections of getters thanks to which you can check the data stored in ZDK or listen to it changes,
• events - provides collection of events that you can listen to.

Actions

Most of the actions returns a promise thanks to which you can wait for response, end of the process or get an error.

For example:

user.actions.open(token).then(() => {
   console.log('show the app!');
 }).catch(err => {
   console.error('show error to user and maybe button to try again!');
 });
};

Data (Getters)

Inside data object, you can find Getters that give you access to different values of the module. You can get the current value and listen to its changes.

For example:

// getting a current value
user.data.status.val() // => 'inactive' | 'loading' | 'active'
// listening to a value change
user.data.status.onChange((status) => {
 console.log(status); // => 'inactive' | 'loading' | 'active'
})
// listening to a value change and immediately getting the current value in the event after setting up the listener (it will always emit a value even the value has not been changed)
user.data.status.onAutoChange((status) => {
 console.log(status); // => 'inactive' | 'loading' | 'active'
})

Events

Inside events object, you can find listenerCreators of various events. Thanks to them, you can create your listener to chosen event.

For example:

webSocket.events.onMessage(packet => {
 console.log(packet);
})

Each of the ‘listenerCreator’ returns a function which cleans the listening to the event. Make sure to call it when you stop using it.

example:

const unlisten = webSocket.events.onMessage(packet => {
 console.log(packet);
})
 
// clear the listener - the console.log will no longer be called.
unlisten();

For most event-like interactions, we recommend to use a Getter from the data object (see above). Each Getter exposes an onChange handler that behaves like an event, but using Getters keeps your logic state-driven and typically more optimal (fewer subscriptions, less churn, clearer data flow).

For example: when someone join room you are able to detect it by listening to:

A onUserEntered event which looks like this:

room.events.onUserEntered(newUser => {
  console.log(newUser); // the new one user which joined to the room
})

Also you are able to listen to Getter members:

room.data.members.onChange(members => {
  console.log(members); // current list with all members including the new one
})

The advantage of using Getter here is that it emits to you whole list of users. Based on that list you can rerender your UI. In the ‘onUserEntered’ event approach you would need to store each of the users by creating your own list with all the users which joined the room to be able to correctly rerender UI.

Some of the data passed by events are not stored in the ZDK, and the Getter is not created for it. For those you need to use listenerCreators. For example onCustomRoomPacket in the room module has no corresponding Getter.