Skip to main content

API

Methods​

getUsers()​

Return current user and all users present in the room.

const {
    animatorId,         // Room animator id
    user,               // Current user
    users               // All other users
} = await getUsers();

The type of animatorId is string, user is IConnectedUser and the type of users is IRoomUser.

getTeams()​

Collect room teams. If the room isn't in team mode, an empty array is returned.

const teams = await getTeams();

The type of teams is IRoomTeam.

getData(id?: string)​

Collect room stored data in globalData object.

  • If no id is given, return all global data.
  • If an id is given, return the global data with id.
// Return all global data
const data = await getData();

// Return only global data with id : 'dataId'
const data = await getData('dataId');

The type of data is IRoomData.

warning

If no global data is found for the given id, the returned value will be undefined.

// Assume that global data is like the following
const globalData = {
    fruit: {
        id: 'fruit',
        value: 'apple'
    }
};

let data = await getData('fruit');
console.log(data.value) // 'apple'

data = await getData('animal');
console.log(data.value);
// Canno't read properties of undefined (data is undefined)

getUserData(userId?: string)​

Collect room stored data in userData object.

  • If no userId is given, return all users data.
  • If an userId is given, return the all data of the given userId.
// Return all users data
const data = await getUserData();

// Return only data of user with id : 'userId'
const data = await getUserData('userId');

The type of data is { [userId]: IRoomData }.

warning

If no user data is found for the given userId, the returned value will be undefined.

// Assume that user data is like the following
const userData = {
    jhon: {
        fruit: {
            id: 'fruit',
            value: 'apple',
        }
    },
    joe: {
        fruit: {
            id: 'fruit',
            value: 'strawberry'
        }
    }
};

let data = await getUserData('jhon');
console.log(data) // { jhon: { fruit: { id: 'fruit', value: 'apple' } } }

data = await getUserData('max');
console.log(data); // { max: undefined }

getConfigFilesPath()​

Return the path of the folder linked to current capsule configuration.

const path = await getConfigFilesPath();

// Fetch config.json path
const res = await fetch(path + '/config.json');
const json = await res.json();

console.log(json) // Print config.json content

getAssets()​

Collect room assets content (tags & files).

const { tags, files } = await getAssets();

The type of tags is ITag[]̀ and the type of files is IFile[].

note

Returned files path are relative to the current instance. If you are on k-hubs.com and returned path is /static/file/.... The full path is https://k-hubs.com/static/file/...

getRoomConfig()​

Collect room configuration.

const config = await getRoomConfig();

The type of configis IRoomConfig.

updateProfile(user: { username?: string; avatar?: string })​

Update current user profile.

const updated = await updateProfile({ username: 'Joe' }); // Update username to "Joe"

The type of updated is IRoomUser.

setData(data: (IData & { isGlobal?: boolean })[])​

Save all given data into the room. For each data:

  • If data.isGlobal === true, then the data will be stored into the globalData object.
  • Else it will be stored into the userData object.
setData([{ id: 'fruit', value: 'apple' }, { id: 'fruit', value: 'strawberry', isGlobal: true }])

console.log(getData('fruit')) // { fruit: { id: 'fruit', value: 'strawberry' } }
console.log(getUserData('fruit')) // { [currentUserId]: { fruit: { id: 'fruit', value: 'apple' } } }
note

data will not be sent to other users. To send data to other users use sendData().

sendData(data: IData[], userIds?: string[])​

Send all given data to other users.

  • If userIds is given, each data will be sent only to given userIds.
  • Else each data will be send to all user.

Each sent data is type of IReceivedData.

// Jhon send data to everyone
const data = [{ id: 'fruit', value: 'apple' }, { id: 'animal', value: 'dog' }];
sendData(data);

// send data only to Joe and Max
sendData(data, ['joe', 'max']);

sendToAnimator(data: IData[])​

Send all given data to the room animator.

const data = [{ id: 'fruit', value: 'apple' }, { id: 'animal', value: 'dog' }];
sendToAnimator(data);
tip

To listen for sendData and sendToAnimator, use onDataSend listener.

sendFiles(files: File[])​

Upload files to current room. Given files must be type of File.

const file1 = new File(); // avatar.png
const file2 = new File(); // text.txt
const uplodedFiles = await sendFiles([file1, file2])

console.log(uploadedFiles); // [{ name: 'avatar', ... }, { name: 'text', ... }]

The type of uploadedFiles is IFile[].

updateFile(fileId: string, name?: string, file?: string)​

Update a previous uploaded file.

const updatedFile = await updateFile('file1', 'New name');
console.log(updatedFile); // { name: 'New name', ... }

The type of updatedFile is IFile.

Listeners​

Use these functions to listen for incoming events from server.

warning

When you register a listener with the on... function and you unregister a listener with the off... function, the given callback to each function must be the same function instance.

// Bad ❌
onUserJoin((user) => { console.log(user) });
offUserJoin((user) => { console.log(user) });

// Good ✅
const callback = (user) => console.log(user);

onUserJoin(callback);
offUserJoin(callback);

onUserJoin(callback: (user: IRoomUser) => void)​

Register a listener for the userJoin event. The given callback is trigered when a user connect to the room. When the callback is trigered, it takes the connected user as parameters. Its type is IRoomUser.

const connectCallback = (user: IRoomUser) => console.log(user);
// Listen for join event.
onUserJoin(connectCallback);

// Jhon connected ...
// Console output: { id: 'jhon', username: 'Jhon', ... }

offUserJoin(callback: (user: IRoomUser) => void)​

Unregister a previous onUserJoin listener.

offUserJoin(connectCallback);

onUserLeave(callback: (userId: string) => void)​

Register a listener for the userLeave event. the given callback is trigered when a user disconnect from the room. When the callback is trigered, it takes the disconnected userId as parameter.

const disconnectCallback = (userId: string) => console.log(userId);
// Listen for leave event.
onUserLeave(disconnectCallback);

// Jhon diconnected ...
// Console output: 'jhon'

offUserLeave(callback: (userId: string) => void)​

Unregister a previous onUserLeave listener.

offUserLeave(disconnectCallback);

onUserUpdate(callback: (user: IRoomUser) => void): void​

Register a listener for the userUpdate event fired when an user call updateProfile().

const userUpdateCallback = (user: IRoomUser) => console.log(user);
// Listen for user update event.
onUserUpdate(userUpdateCallback);

// Jhon update his username to 'Jhon Doe' ...
// Console output: { 'id': 'jhon', username: 'Jhon Doe' }

offUserUpdate(callback: (user: IRoomUser) => void): void​

Unregister a previous `onUserUpdate listener.

offUserUpdate(onUserUpdateCallback);

onDataSend(dataId: string, callback: (data: IReceivedData) => void)​

Register a listener for a specific event. The given callback is triggered when sendData (or sendToAnimator if the current user is animator) is called with the given dataId. It takes the sended data as parameters. Its type is IReceivedData.

const onFruitCallback = (data: IReceivedData) => console.log(data);
onDataSend('fruit', onFruitCallback);

// Jhon sendData({ id: 'fruit', value: 'apple' })
// Console output: { id: 'fruit', value: 'apple', senderUserId: 'jhon' }

offDataSend(dataId: string, callback: (data: IReceivedData) => void)​

Unregister a previous onDataSend listener.

offDataSend('fruit', onFruitCallback);