Universal API for realtime services. Integrate once and easily switch between Socket.io, Ably and PubNub.
Provides handy methods for rooms, users, message history, and information about connected user.
Supported realtime services:
Setup
NPM
Install via NPM.
npm install urltm --save
Include library via require.
const urltm = ;
Web
Install via bower or NPM
npm install urltm --savebower install urltm --save
Include library in HTML.
Configure
Both the NodeJS and web libraries are configured with the urltm
variable.
let user = ;
service
is the name of the realtime service to use (ably
,pubnub
orsocketio
)config
is a Javascript object with a config for that service.
PubNub or Socket.io
Set Up With Socket.io
Socket.io is an open source websocket framework. To use socket.io, you'll run your own socket.io server on the back end.
Set Up With PubNub
PubNub is a hosted realtime solution that doesn't require you to run or maintain any servers.
Set Up With Ably
Ably is a hosted realtime solution that doesn't require you to run or maintain any servers.
Usage
Users
Every user
connected to urltm.js has two properties:
uuid
- a unique way to identify thisuser
state
- data associated with thisuser
You can provide these as parameters during initialization.
let user = ;
Rooms
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;
This returns a room
object which we can use to communicate with other user
s.
Join Event
A room can subscribe to the join
event to find out when other user
s join the room.
room;
Messages
Message Event
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;
Publish
To send a message to the entire room
, use the message()
method. Returns a promise.
room;
Online Users
Here Now
A room
can get a list of other user
s who have in the room
by using the here()
method. Returns a promise.
room;
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'
Leave Event
A room
can subscribe to the leave
event to find out when a user
leaves.
room;
A user
can manually leave a room
by using the leave()
method. Returns a promise.
room;
This will fire the leave
event.
Disconnect
If a user
gets disconnected without leaving the room, the disconnect
event will fire.
room;
Set User 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;
This will fire the state
event which you can subscribe to with the room.on()
method. When fired you will get the uuid
of the user
and the new state
.
room;
Get Old Messages
A user
can retrieve previously published messages in the room
by using the history()
method. Returns a promise.
roomhistory;
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'
Test
Tests are run with mocha and chai.
npm install mocha -gnpm install chai -g
Set environment variable CLIENT
to test each service.
env CLIENT=ably mocha
env CLIENT=pubnub mocha
env CLIENT=socketio mocha