1

Universal API for Realtime Use a single code base to connect to multiple realtime services.

Demo


Swap between Socket.io and PubNub with a single API. Works on web and NodeJS.

Setup


Socket.io

let user = rltm({
    service: 'socketio', 
    config: {
        endpoint: 'http://localhost:8000'
    }
});

Don't forget to run the socket.io server.

PubNub

let user = rltm({
    service: 'pubnub', 
    config: {
        publishKey: 'YOUR_PUBNUB_PUBLISH_KEY',
        subscribeKey: 'YOUR_PUBNUB_SUBSCRIBE_KEY'
    }
});

Docs


Users

Every user connected to rltm.js has two properties:

  1. uuid - a unique way to identify this user
  2. state - data associated with this user

You can provide these as parameters during initialization.

let user = rltm({
    service: 'socketio', 
    config: {
        endpoint: 'http://localhost:9000',
        uuid: 'MY_UNIQUE_ID',
        state: {admin: true}
    }
});

Rooms

Realtime communication happens over rooms. rooms are like chat rooms, everybody in a room receives events sent by every other user.

Join

A user can join a room by using the join() method and supplying a room identifier. users who provide the same identifier will be able to communicate with each other.

room = user.join('room-name');

This returns a room object which we can use to communicate with other users.

A user can subscribe to the join event to find out when other users join the room.

room.on('join', (uuid, state) => {
    console.log('user with uuid', uuid, 'joined with state', state);
});

Message

To send a message to the entire room, use the message() method. Returns a promise.

room.message({hello: world}).then(() => {
    console.log('message published');
});

When another user sends a message to the room, it will trigger the message event. The room can subscribe to that event with the on() method.

room.on('message', (uuid, data) => {
    console.log('message received from uuid', uuid, 'with data', data);
});

History

Retrieve previously published messages in the room by using the history() method. Returns a promise.

room.history().then((history) => {
    console.log('got array of all messages in channel', history);
});

It will return the last 100 messages as an array of objects containing the uuid and data of every message. The array is sorted newest to oldest.

[ 
    { 
        uuid: uuid2, 
        data: { 
            sentTime: '2pm',
            text: 'boy howdy' 
        } 
    }, 
    { 
        uuid: uuid1, 
        data: { 
            sentTime: '1pm',
            text: 'hello there' 
        } 
    }
]

State

A user state can be updated at any time by using the state() method. Supply the new state as the only parameter. Return a promise.

room.state({idle: true}).then(() => {
    console.log('state set');
});

This will fire the state event which you can subscribe to with the on() method. When fired you will get the uuid of the user and the new state.

room.on('state', (uuid, state) => {
    console.log('user with uuid', uuid, 'was given state', state);
});

Here

A room can get a list of other users who are in the room by using the here() method. Returns a promise.

room.here().then((users) => {
    console.log('users online', users);
});

Successful responses will return a object of users who are currently connected to the room. The keys are the user's uuids and the values are their current state.

{ 
    uuid1: {
        username: 'ianjennings'
    },
    uuid2: {
        username: 'stephenblum'
    }
}

Leave

A user can manually leave a room by using the leave() method. Returns a promise.

room.leave().then(() => {
    console.log('left the room.');
});

A room can subscribe to the leave event to find out when a user leaves.

room.on('leave', (uuid) => {
    console.log('user with uuid', uuid, 'has left');
});