Presence

Presence allows clients to know when other clients come online and offline, as well as the ability to query for connected clients.

It’s worth mentioning that presence only shows clients that logged in with a username. For example, client.login() won’t trigger the callback client.presence.subscribe(callback).

Methods

client.presence.subscribe( username, callback )

Argument	Type	Optional	Description
username	String	true	A username that should be subscribed to.
callback	Function	false	Will be invoked with the username of a client, and a boolean to indicate if it was a login(true) or logout(false) event

Subscribes to presence events. Callback will receive the username of the newly logged in/out user

// Client A
client.presence.subscribe((username, isLoggedIn) => {
  // handle every new user login/logout
})

client.presence.subscribe('Alex', (username, isLoggedIn) => {
  // handle Alex only
})

// Client B
client.login({username: 'Alex'})

client.presence.unsubscribe( username, callback )

Argument	Type	Optional	Description
username	String	true	The username that was subscribed to.
callback	Function	true	A previously registered named callback

Removes a previously registered presence callback. If no callback is provided all presence subscriptions will be removed.

function onOnlineStatusChange( username, isOnline ) {
  //...
}
// Client A
client.presence.subscribe( onOnlineStatusChange )
// unsubscribe callback
client.presence.unsubscribe( onOnlineStatusChange )

// unsubscribe all presence callbacks for a previously subscribed username
client.presence.unsubscribe( 'username' )

// unsubscribe all
client.presence.unsubscribe()

client.presence.getAll( usernames, callback )

Argument	Type	Optional	Description
usernames	Array	true	An array of specific usernames that should be queried.
callback	Function	false	A function that will be called with an error value and an array or object of usernames that are online

Queries for currently connected clients

// Client B
client.presence.getAll((error, clients) => {
    // error = null, clients = [ 'Alex', 'Ben', 'Charlie' ]
})

Query for specific users

// Client B
client.presence.getAll(['Alex', 'Pedro',], (error, clients) => {
    // error = null, clients = {Alex: true, Pedro: false}
})