Presence API Service

The Presence API Service provides methods to get and set the presence of an end user in a project, that is, to indicate whether the end user is online. This happens automatically: in projects that use channels, the end user's presence is published automatically on a "presence" channel that is specific to each group. You can also use the Presence API Service to do this explicitly: you can make a call to indicate that a particular end user is online or offline.

The Presence API Service is only needed for Authenticated projects, that is, team projects with end users and groups. It is typically used only in multiplayer projects, to facilitate end users communicating with each other. It is based on the query capabilities of the underlying RESTful Presence API.

 var pr = new F.service.Presence();
 pr.markOnline('example-userId');
 pr.markOffline('example-userId');
 pr.getStatus();

Constructor options

Required?	Name	Type	Description
	groupName	string	Epicenter group name. Note that this is the group name, not the group id. If left blank, taken from the session manager.
	account	string	The account id. In the Epicenter UI, this is the Team ID (for team projects) or User ID (for personal projects). Defaults to undefined. If left undefined, taken from the URL.
	project	string	The project id. Defaults to undefined. If left undefined, parsed from the URL.
	token	string	For projects that require authentication, pass in the user access token (defaults to undefined). If the user is already logged in to Epicenter, the user access token is already set in a cookie and automatically loaded from there. (See more background on access tokens). @see Authentication API Service for getting tokens.
	transport	JQueryAjaxOptions	Options to pass on to the underlying transport layer. All jquery.ajax options are supported.
	server	object
	server.host	string	The value of host is usually the string api.forio.com, the URI of the Forio API server. This is automatically set, but you can pass it explicitly if desired. It is most commonly used for clarity when you are hosting an Epicenter project on your own server
	server.protocol	https / http	Defaults to https

Methods

markOnline([userId, options])

Marks an end user as online.

Parameters

Required?	Name	Type	Description
	userId	string	optional If not provided, taken from session cookie.
	options	Object	Additional options to change the presence service defaults.

Returns

Promise - Promise with presence information for user marked online.

Example

var pr = new F.service.Presence();
    pr.markOnline('0000015a68d806bc09cd0a7d207f44ba5f74')
         .then(function(presenceObj) {
              console.log('user ', presenceObj.userId, 
                   ' now online, as of ', presenceObj.lastModified);
         });

markOffline([userId, options])

Marks an end user as offline.

Parameters

Required?	Name	Type	Description
	userId	string	If not provided, taken from session cookie.
	options	Object	Additional options to change the presence service defaults.

Returns

Promise - Promise to remove presence record for end user.

Example

var pr = new F.service.Presence();
pr.markOffline('0000015a68d806bc09cd0a7d207f44ba5f74');

getStatus([groupName, options])

Returns a list of all end users in this group that are currently online.

Parameters

Required?	Name	Type	Description
	groupName	string	If not provided, taken from session cookie.
	options	object	Additional options to change the presence service defaults.

Returns

Promise - Promise with status of online users

Example

var pr = new F.service.Presence();
pr.getStatus('groupName').then(function(onlineUsers) {
     for (var i=0; i < onlineUsers.length; i++) {
          console.log('user ', onlineUsers[i].userId, 
               ' is online as of ', onlineUsers[i].lastModified);
     }
});

getStatusForUsers(userList[, groupName, options])

Appends a boolean 'isOnline' field to provided list of users

Parameters

Required?	Name	Type	Description
Yes	userList	Array.<{ userId: string }>	Users to get status for
	groupName	string	If not provided, taken from session cookie.
	options	object	Additional options to change the presence service defaults.

Returns

Promise - Promise with status of online users

Example

var pr = new F.service.Presence();
pr.getStatusForUsers([{ userId: 'a', userId: 'b'}]).then(function(onlineUsers) {
     console.log(onlineUsers[a].isOnline);
});

getChannel([groupName, options])

End users are automatically marked online and offline in a "presence" channel that is specific to each group. Gets this channel (an instance of the Channel Service) for the given group. (Note that this Channel Service instance is also available from the Epicenter Channel Manager getPresenceChannel().)

Parameters

Required?	Name	Type	Description
	groupName	string	If not provided, taken from session cookie.
	options	Object	Additional options to change the presence service defaults

Returns

Channel - Channel instance

Example

var pr = new F.service.Presence();
var cm = pr.getChannel('group1');
cm.publish('', 'a message to presence channel');

Channel instance for Presence channel