insto-nodejs
Node.js client library for Insto.co.uk
You will require a valid Insto API key, which can be acquired by signing up for free at Insto.co.uk
Full documentation for the HTML/JS library can be found at the docs page, which translate identically to the Node.js module. Examples below.
Setup
npm install insto
The InstoClient object
The InstoClient object is used to interact with Insto, create a new instance as shown below:
var insto = require('insto');
var InstoClient = new insto.InstoClient(API_KEY, userData, userQuery, {
onConnect: function(data) {
console.log(data);
},
onConnectedUsers: function(data) {
console.log(data);
},
onNotification: function(data) {
console.log(data);
},
onQuery: function(data) {
console.log(data);
},
onUserConnect: function(data) {
console.log(data);
},
onUserDisconnect: function(data) {
console.log(data);
}
});
API_KEY (required)
The API key required to access Insto
userData (required)
This is a Javascript object that describes the user making the connection, for example:
var userData = {"name": "Matt", "userId": 5, "userType": "admin"};
userQuery (optional - defaults to false)
This is a Javascript object that describes the other connected users that this user wants to receive connect/disconnect notifications for
var userQuery = {"userType": "sales"};
This would return any other connected user that has a userType equal to 'sales'.
callbacks (optional - default does nothing)
This is a Javascript object that defines the numerous callback functions that are fired upon receiving notifications from the Insto server.
{
onConnect: function(data) { ... },
onConnectedUsers: function(data) { ... },
onNotification: function(data) { ... },
onQuery: function(data) { ... },
onUserConnect: function(data) { ... },
onUserDisconnect: function(data) { ... }
}
What are notifications
Any InstoClient can receive realtime notifications via the InstoClient object. Each time one of these notifications are received, they are passed to the callback function (if it has been supplied).
There are six types of notification:
- onConnect - received when you have successully connected to the Insto server
- onUserConnect - received when another Insto client connects to the server and matches the supplied userQuery. Provides this clients userData object.
- onUserDisconnect - received when another Insto client disconnects from the server and matches the supplied userQuery. Provides this clients userData object.
- onConnectedUsers - received after connection if any currently connected Insto clients match the supplied userQuery. Provides an array of matching clients userData objects.
- onNotification - received when this Insto client matches the parameters specified by another client when sending a message. Provides the sent message.
- onQuery - received as a response from the query method (insto.query()). Provides an array of other connected users that match the supplied query.
All notifications return a Javascript object with the unique ID of the sending client in the _id property where appropriate. For example:
{"message":"this is a message","_id": "sdkjfhgsdf-e45"}
It is important to remember that all Insto notifications returned by the onNotification callback are schema-less, and as such can be in any format as defined by the sender, as long as they are valid Javascript objects. However they will always contain the _id property.
onConnect notifications
This notification is received when the InstoClient has successully connected to the server. It simply returns the unique _id of this connected InstoClient.
{
"_id": "sdkjfhgsdf-e45"
}
onUserConnect / onUserDisconnect notifications
These types of notification are sent when a InstoClient changes it's connection state. If this InstoClient matches a supplied userQuery of another InstoClient they will receive a connect/disconnect notification, alerting them to this change of state.
{"userId":10,"firstname":"James","lastName":"Robinson","userType":"test","_id": "sdkjfhgsdf-e45"}
{"userId":10,"firstname":"James","lastName":"Robinson","userType":"test","_id": "sdkjfhgsdf-e45"}
onConnectedUsers
If a userQuery is supplied on connection, a connectedusers notification is automatically returned after a connection to the server is made. There will be a 'users' property which contains an array of userData objects for all of the currently connected InstoClients that match the supplied userQuery.
{
"users":[
{ "userId":1,
"firstname":"James",
"lastName":"Robinson",
"userType":"sales",
"_id":"sdfjkgsdf-3435"
},
{ "userId":2,
"firstname":"Gregg",
"lastName":"House",
"userType":"sales",
"_id":"wesdfsdfsdf-234"
},
{ "userId":3,
"firstname":"Dave",
"lastName":"Johnson",
"userType":"sales",
"_id":"cbnmbnmcb9udfg-4569"
}
]
}
onQuery
This notification type is returned to the same Insto Client that calls the query method. It returns with an array of users that match the supplied query, very much like the 'connectedusers' notification.
{
"users":[
{ "userId":1,
"firstname":"James",
"lastName":"Robinson",
"userType":"sales"
},
{ "userId":2,
"firstname":"Gregg",
"lastName":"House",
"userType":"sales"
},
{ "userId":3,
"firstname":"Dave",
"lastName":"Johnson",
"userType":"sales"
}
]
}
Methods
These are the methods used to interact with the service
InstoClient.send( userQuery, message, [sendToSelf] ) - Send a notification to a subset of users
Parameters
userQuery - [required] define the user(s) that this notification should be sent to
message - [required] define the message that should be sent
sendToSelf - [optional - default: false] should this message be sent to the message sender (only if they match the userQuery)
The Insto Client can send a notification to any other connected Insto Client by providing a userQuery. All users who match this query will receive the message. If the sending user matches the userQuery they will not receive the message unless the sendToSelf parameter is defined as true.
A userQuery must be a valid Javascript object, as must the message. If a message is required to go to all connected users, please use the Insto Client.broadcast() method.
Example of a valid userQuery:
var query = {
"userType": "sales",
"branch": "middlesbrough"
}
Messages sent via Insto are schema-less, and although they must be a valid Javascript object, they can have any structure as required by the calling application.
A simple message object:
var message = {
"text": "This is an example message"
}
A more complicated message object, still perfectly valid:
var message = {
"type": "error",
"detail": {
"codes": [101, 202, 123],
"text": "There was an error"
}
}
The below example shows a simple message being sent to all users that have a 'userType' of 'sales':
//message query
var query = {"userType": "sales"};
//create a message object to be sent to all matching users
var msg = { "message": "This is an example message" };
//send!
InstoClient.send(query, msg);
InstoClient.broadcast( message ) - Send a notification to all users
Parameters
message - [required] define the message that should be sent
Use this method to send a message to all connected Insto Clients. The message object obeys the same rules as the Insto Client.send() method.
//create a message object to be sent to all users
var msg = { "message": "This is an example message" };
//broadcast message to all
InstoClient.broadcast(msg);
This would send a message to all users.
InstoClient.query( userQuery ) - Find all connected users that match a userQuery
Parameters
userQuery - [required] define the user(s) that this query should return
It is possible to search the connected InstoClients to see if there are any that match the required subset.
This method requires a userQuery object to be passed in.
Example of a valid userQuery:
var query = {
"userType": "sales",
"branch": "middlesbrough"
}
All matching users are returned in a notification of type 'query'.
An example of using InstoClient.query();
//create a message object to be sent to all users
var query = {
"userType": "sales",
"branch": "middlesbrough"
}
//send query
InstoClient.query(query);