1
Swap between Socket.io, Ably and PubNub with a single API. Works on web and NodeJS.
Socket.io
let user = urltm({
service: 'socketio',
config: {
endpoint: 'http://localhost:8000'
}
});
Don't forget to run the socket.io server.
Ably
let user = urltm({
service: 'ably',
config: {
key: 'YOU_ABLY_API_KEY',
clientId: 'YOUR_UNIQUE_CLIENT_ID_FOR_PRESENCE'
}
});
PubNub
let user = urltm({
service: 'pubnub',
config: {
publishKey: 'YOUR_PUBNUB_PUBLISH_KEY',
subscribeKey: 'YOUR_PUBNUB_SUBSCRIBE_KEY'
}
});
Every user
connected to urltm.js has two properties:
uuid
- a unique way to identify this user
state
- data associated with this user
You can provide these as parameters during initialization.
let user = urltm({
service: 'socketio',
config: {
endpoint: 'http://localhost:9000',
uuid: 'MY_UNIQUE_ID',
state: {admin: true}
}
});
Realtime communication happens over room
s. room
s are like chat rooms, everybody in a room
receives events sent by every other user
.
A user
can join a room
by using the join()
method and supplying a room
identifier. user
s 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 user
s.
A user can subscribe to the join
event to find out when other user
s join the room.
room.on('join', (uuid, state) => {
console.log('user with uuid', uuid, 'joined with state', state);
});
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);
});
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'
}
}
]
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);
});
A room
can get a list of other user
s 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 user
s who are currently connected to the room
. The keys are the user
's uuid
s and the values are their current state
.
{
uuid1: {
username: 'ianjennings'
},
uuid2: {
username: 'stephenblum'
}
}
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');
});