Device Presence

Presence

Emitter provides a presence service, seamlessly integrated with the entire service and transparent for the users. The presence can be used for game lobbies, chat rooms and machine-to-machine communication. For such applications it could be useful to see how many people are subscribed to a channel, or even to see which users are subscribed. For certain applications you might trigger an event if the number of users exceeds a certain value.

There are two ways of retrieving presence information, which are complementary in nature: 1. Get current subscribers: receive a status message that describes quantity of subscribers and user names of subscribers upon request. 2. Get subscription updates: Receive a change notification each time a user subscribes or unsubscribes.

Current subscribers

At any time, you can retrieve a list of the current subscribers and the total number of subscribers of a channel by calling the presence function in your application. You must specify a valid security key which has a presence retrieval permission (p flag). For example, in order to request for a message to see the connections to channel chat/sports/, we can call presence() function as shown here:

emitter.presence({
  key: "<channel key>",
  channel: "chat/sports",
  status: true,
  changes: false 
});

Different arguments of this function allow you to specify the presence information to retrieve.

• key: The channel key. It should have a presence retrieval permission (p flag) matching the channel.
• channel: The name of the channel. Can also contain wildcards or partial channels. More details about using presence in combination with wildcards or partial channels are provided in the next section.
• status: Boolean value that indicates whether you want to receive a response from the emitter broker about the current subscribers.
• changes: Boolean value that indicates whether you want to get a push notification each time a client (un)subscribes to the channel .

In the above example you would get an immediate response from the emitter broker, containing the list of users currently subscribed to the channel. An example of such response is shown below.

{
  event: "status",
  channel: "chat/sports",
  occupancy: 2,
  time: 1471771395,
  who: [{
   id: "Ekm4hAAAAABesHHK",
   username: "user1"
  },
  {
   id: "A4EcAAAAABesHHE",
   username: "user2"
  }]
}

• event: indicates the type of the event response, can be several different values:
• "status": a response that contains a list of currently subscribed clients.
• "subscribe": an event (push notification) that contains a user who has subscribed.
• "unsubscribe": an event (push notification) that contains a user who has unsubscribed.
• channel: indicates the target channel for the response/event.
• occupancy: indicates current number of subscribers of the target channel.
• time: indicates the time of the event, a unix timestamp.
• who: array with all users that are subscribed to the channel. The maximum number of users displayed is 1000. In case there are more users subscribed, the array contains a random set of 1000 users is displayed. Note that users get identifiers generated internally by emitter, but you have a possibility to specify a username during the emitter.connect() function call, as demonstrated below.

client = emitter.connect({ username: "user1" });

Subscription updates

There are many cases where retrieving a status is not enough and you might be interested receiving real-time presence notifications each time a user subscribes or unsubscribes from a channel. For example, for chat/sports/ channel shown below, we call the presence() function with changes flag set to true.

emitter.presence({
  key: "<channel key>",
  channel: "chat/sports",
  status: false,
  changes: true
})

This is the same function as for getting the current presence status, except now the status argument is set to false and the changes argument is set to true. In the above example you will now get a message from the emitter broker each time a user (un)subscribes from the chat/sports/ channel.

{
  event: "subscribe",
  channel: "chat/sports/",
  occupancy: 2,
  time: 1471771395,
  who: {
   id: "A4EcAAAAABesHHE",
   username: "user2" 
   }
}

• event: "subscribe" if a user subscribed or "unsubscribe" if a user unsubscribes.
• channel: displays the channel -occupancy: the number of subscribers to this channel after this event.
• time: time of the event, as a unix time.

• who: user (connection id and an optional username) that have (un)subscribed.

If you want to stop receiving these push notifications, you simply call the presence() function once again with the changes argument set to false:

emitter.presence({
  key: "<channel key>",
  channel: "chat/sports",
  status: false,
  changes: false 
})

Wildcards or partial channels

When you request presence for a channel, you will get presence information for the exact channel you specified. In some cases users might have subscribed to channels using wildcards or partial channels. The below example explains how presence works in combination with wildcards or partial channels. Suppose users are subscribed as follows:

This would also exactly be the occupancy (number of users) you wouldd get back if you asked for presence information to the emitter service for these channels. Please be aware that in the above example in fact 13 users receive messages from channel chat/sports/. However, only 10 users are subscribed to the exact channel chat/sports/. So if you would request presence information for channel chat/sports/ you would get an occupancy of 10, for channel chat/+/ you would get occupancy of 2 and so on. Also subscription updates are only provided for the exact channel you ran the presence fuction for. So depending on the use case it might be necessary to request presence information for channels chat/sports/, chat/+/ and chat/ separately and sum up the occupancy data yourself.

Further Reading

That's it for the presence. Feel free to contact us if you have any particular questions and contribute to this guide if you feel that something is unclear or requires more explanations. On a final note, there are few more resources you might want to check out, including some demos and source code for a complete application that demonstrates our presence feature.

• Presence Demo
• Example Source Code