SightCall Developer Center

Account Login Support

Presence and Roster Management

Overview

This section is dedicated to the Javascript implementation of the Presence and Roster features.

The presence is a integer value that represents the status of a user. The only reserved value is 0 that indicates the user is not currently connected.

Presence Values

When a user is not connected, his presence is set to 0. The meaning of the 0 value is reserved and cannot be changed.

When a user connects, his/her presence value remains 0 until he/she changes it to any other value.

Presence has to be explicitly changed to any other value by the web application.

Except for 0, it is the responsibility of the web application to define what the presence values mean. For example an application 'A' can set up the following lookup table:

Presence Meaning
0 Not connected
1 Available
2 Busy
3 Already on a call
4 Will be back soon

And an application 'B' can use very different values:

Presence Meaning
0 Not connected
10 Available
20 Writing a message
30 Responding to a message
40 Asleep, do not disturb
41 Asleep, call only for urgent matter
42 Asleep, please wake me up with a call

Presence is set up by the application on a user side, and interpreted by the application on the contact side, so the app can give any meaning to any value, except for 'not connected' which will always be 0.

User Registration

Users are automatically registered to the presence servers once authenticated. By default the presence is set to 0. It is the applications' responsibility to change it to another value.

After registration, the event presence.ok is fired to notify the application that the user is registered on the presence server. An additional event occurs just after to indicate if the user is already connected(presence.alreadyregistered) or not (presence.newuser).

If this is the first connection for this user, the event presence.alreadyregistered is fired. The associated callback should load the roster and set the presence value of the current authenticated user.

If this isn't the first connection (the user is already connected on another system or another tab) the event received is presence.newuser, in which case it is not necessary to initialize the roster.

In both cases a call to getRoster is necessary so that we are given the current state of the users in your roster before their individual presence changes.

function justArrived(){
    var presence = 15;
    rtcc.setMyPresence(presence);
  }
rtcc.on('presence.newuser',justArrived);
[[Rtcc instance]setPresenceDelegate:thePresenceDelegate];

//in the PresenceDelegate
- (void) rtccPresenceRegistrationUpdate:(registrationUpdate_t)registrationUpdate{
  NSLog(@"Update of the Presence Registration");
}
Rtcc.instance().setPresenceDelegate(thePresenceDelegate)

//in the PresenceDelegate
func rtccPresenceRegistrationUpdate(registrationUpdate: registrationUpdate_t) {
  println("Update of the Presence Registration")
}
@RtccEventListener
public void onRegistrationEvent(RegistrationEvent event) {
    RegistrationEvent.Status status = event.getStatus();
    if (status == REGISTERED || status == ALREADY_REGISTERED) {
        // User is registered
    }
}

Setting up its own presence

The application can set the presence of a user side by calling the setMyPresence() method.

function initPresence(){
    var presence = 15;
    rtcc.setMyPresence(presence);
  }

rtcc.on('presence.newuser',initPresence);
  uint8_t presence = 15;
  [[Rtcc instance] setPresence: presence]
  var presence = 15
  Rtcc.instance().setPresence(presence)
Rtcc.instance().presence().set(5);

The application is notified that the change has been successfully processed


function presenceUpdated(data) {
  for(var i=0; i<=data.length; i++){
    console.log(data[i].uid +" 's status is:" + data[i].presence);
  }
}

rtcc.on('presence.update',presenceUpdated);
- (void)rtccPresenceContact:(NSString *)contact changedPresence:(NSNumber *)presence {
  //if contact is equal to your UID, then it is your presence that was updated
  NSLog(@"%@ changed its presence: %d", contact, [presence intValue]);
}
func rtccPresenceContact(contact: String!, changedPresence presence: NSNumber!) {
  //if contact is equal to your UID, then it is your presence that was updated
  println("\(contact!) changed its presence: \(presence!)")
}
@RtccEventListener
public void onPresenceUpdateEvent(PresenceUpdateEvent event) {
    String uid = event.getUid();
    int value = event.getValue();
}

Checking the presence of another user

Once the web application has received 'presenceOkNewUser' or 'presenceOkAlreadyRegistered' message in the onConnectionHandler [LINK], a user can check the presence of any other user using the getPresence() method.

var uidListToCheck = [ 'user23', 'user346'];
rtcc.getPresence(uidListToCheck);
NSArray *contacts = @[@"user23", @"user346"];
[[Rtcc instance]getPresenceForContacts:contacts];
var contacts = ["user23", "user346"]
Rtcc.instance().getPresenceForContacts(contacts)
Rtcc.instance().presence().request("JellyBean", "KitKat", "Lollipop");

The result is sent back within the event presence.burstupdate.

function burstUpdate(usersUpdated) {
//Note that getPresence and the callback associated to presence.burstupdate take an array as parameter.
 for(var i=0; i<=usersUpdated.length; i++){
   console.log(usersUpdated[i].uid +" 's status is:" + usersUpdated[i].presence);
 }
}

rtcc.on('presence.burstupdate',burstUpdate)
- (void)rtccPresenceForContacts:(NSDictionary *)contactsPresence 
{
  //this dictionary contains the UID of the contacts and their presence as <NSString *ContactUID: NSNumber *Presence>
}
func rtccPresenceForContacts(contactsPresence: [NSObject : AnyObject]!) {
  //this dictionary contains the UID of the contacts and their presence as <NSString *ContactUID: NSNumber *Presence> 
}
@RtccEventListener
public void onPresenceRequestEvent(PresenceRequestEvent event) {
    Map<String, Integer> presences = event.get();
    // Iterate over this map to get all presence values
}

Adding users to a roster

Roster

A Roster is a list of contacts built by a user. Each time the presence of a member of the list changes, the owner of the roster is immediately notified. No need to pull for data, a callback is fired by any change.

Important Notices

The Roster is linked to a user. Should a user (identified by a uid) be connected at the same time on several locations (Rtccdriver, several tabs in WebRTC, mobile device), the roster is shared amongst all the connections. If the mobile app adds a uid in the roster, notifications that the presence of a contact changed are also sent to the web application.

No roster data is permanently stored on the platform, therefore the lifetime of the roster is limited to the connection of a user. Once a user is disconnected from the cloud, the roster is lost and cannot be reloaded. If using the driver it means that the roster is destroyed at disconnection, in webRTC this happens even at reload of the page. Of course, if the user is registered on several devices, then the roster is destroyed when all connections are stopped.

Adding a user in the roster

var uidList = ['Alice1'];
rtcc.rosterAdd(uidList);
NSArray *uidList = @[@"Alice1"];
[[Rtcc instance] addContactsToRoster:uidList];
var uidList = ["Alice1"]
Rtcc.instance().addContactsToRoster(uidList)
Rtcc.instance().roster().add("Alice1");

and the event presence.roster.update is fired to inform the application thet the roster has been updated.

This callback is triggered with two parameters: updates notify you of the number of contacts added (or removed), and the new length of your roster.

function rosterUpdate(updated, length) {
   var nbUpdated = Number(data.updated)
   if (nbUpdated > 0){
     console.log("you added " + nbUpdated + " people to your roster");
   } else{
     console.log("you removed " + Math.abs(nbUpdated) + " people from your roster");
   }
   console.log("your roster's length is " + length);

}
- (void)rtccRosterSize:(NSNumber *)currentSize update:(NSNumber *)variation 
{
  NSLog(@"Delta: %d, Current Size: %d", variation, [currentSize intValue]);
}
func rtccRosterSize(currentSize: NSNumber!, update variation: NSNumber!) {
  println("Delta: \(variation), Current Size: \(currentSize)")
}
@RtccEventListener
public void onRosterEvent(RosterEvent event) {
    int delta = event.getDelta();
    int size = event.getSize();
    Rtcc.instance().presence().request();
}

As rosterAdd takes a list as parameter, several users can be added to a roster at once

var uidList = ['Alice1','Bob123','Carol1'];
rtcc.rosterAdd(uidList);
NSArray *uidList = @[@"Alice1", @"Alice2", @"Alice3"];
[[Rtcc instance] addContactsToRoster:uidList];
var uidList = ["Alice1", "Alice2", "Alice3"]
Rtcc.instance().addContactsToRoster(uidList)
Rtcc.instance().roster().add("Alice1", "Alice2", "Alice3");

In that case the data returned in the callback (Assuming that Alice1 was previously added)

nbUpdated='+2'
length='3'
- (void)rtccRosterSize:(NSNumber *)currentSize update:(NSNumber *)variation 
{ 
  //delta should be 2, and the current size should be 3
}
func rtccRosterSize(currentSize: NSNumber!, update variation: NSNumber!) {
  //delta should be 2, and the current size should be 3
}
@RtccEventListener
public void onRosterEvent(RosterEvent event) {
    int delta = event.getDelta();
    int size = event.getSize();
    // delta will be 2, and size will be 3
}

Once added a contact in your roster, the app is automatically notified of any change of presence, however, the current value of the presence is not automatically initialized. A call to getRoster sends immediate event presence.update with presence of all members of the roster.

Removing a user from the roster

Removing a user from the roster is done through the rosterRemove method.

var uidList = ['Alice1'];
rtcc.rosterRemove(uidList);
  NSArray *uidList = @[@"Alice1", @"Alice2"]
  [[Rtcc instance] removeContactFromRoster:uidList]
  var uidList = ["Alice1", "Alice2"]
  Rtcc.instance().removeContactsFromRoster(uidList)
Rtcc.instance().roster().remove("Alice1");

Like for adding a uid in the roster, the method fires the onRosterUpdated() callback.

Retrieving the current roster

The roster's current state can be loaded by the app using the getRoster method.

Receiving notifications

When the presence of a user in the roster is updated, the current authenticated user receives the notification via the presence.update event.


 function onPresenceUpdate(data) {
  for(var i=0; i<=data.length; i++){
    console.log(data[i].uid +" 's status is:" + data[i].presence);
   }
 }
 rtcc.on('presence.update',onPresenceUpdate)
- (void)rtccPresenceContact:(NSString *)contact changedPresence:(NSNumber *)presence 
{
  NSLog(@"%@ changed its presence: %d", contact, [presence intValue]);
}
func rtccPresenceContact(contact: String!, changedPresence presence: NSNumber!) {
  println("\(contact!) changed its presence: \(presence!)")
}
@RtccEventListener
public void onPresenceUpdateEvent(PresenceUpdateEvent event) {
    String uid = event.getUid();
    int value = event.getValue();
}