Presence channels

Presence channels build on the security of Private channels and expose the additional feature of an awareness of who is subscribed to that channel. This makes it extremely easy to build chat room and “who’s online” type functionality to your application. Think chat rooms, collaborators on a document, people viewing the same web page, competitors in a game, that kind of thing.

Presence channels are subscribed to from the client API in the same way as private channels but the channel name must be prefixed with presence-. As with private channels a HTTP Request is made to a configurable authentication URL to determine if the current user has permissions to access the channel (see Authenticating Users). The main difference is that within the response to the HTTP authentication request the developer can provide additional information about that user, which can then be used within your application.

Information on users subscribing to, and unsubscribing from a channel can then be accessed by binding to events on the presence channel and the current state of users subscribed to the channel is available via the channel.members property.

Presence channels must be prefixed with presence-. See channel naming conventions.

Presence channel subscriptions must be authenticated. See Authenticating Users.

Note: This is not the same as jabber style “which of my friends are online” presence. Pusher doesn’t offer anything out of the box for that use case right now.

Subscribe

When subscribing the user authentication process will be triggered.

var presenceChannel = pusher.subscribe(presenceChannelName);
  • presenceChannelName (String)
    • The name of the channel to subscribe to. Since it is a presence channel the name must be prefixed with presence-.
  • Returns
    • An object which events can be bound to. See binding to events for more information.
PTPusherPresenceChannel *presence = [client subscribeToPresenceChannelNamed:@"chat" delegate:self];
  • presenceChannelName (String)
    • The name of the channel to subscribe to. Since it is a presence channel the name must be prefixed with presence-.
  • Returns
    • An object which events can be bound to. See binding to events for more information.

It is recommended to implement PTPusherPresenceChannelDelegate protocol, to receive notifications for members subscribing or unsubscribing from the presence channel.

Unsubscribe

See unsubscribing from channels.

Accessing channel members

Documentation for accessing channel members is only presently available for the Pusher JavaScript library. For other libraries please see the README file.

A Presence channel has a members property. This object represents the state of the users that are subscribed to the presence channel. The members object has the following properties and methods:

members.count (Number)

A property with a value that indicates how many members are subscribed to the presence channel.

var count = presenceChannel.members.count;

members.each(function) (Function)

The members.each function is used to iterate the members who are subscribed to the presence channel. The method takes a single function parameter which is called for each member that is subscribed to the presence channel. The function will be pass a member object representing each subscribed member.

presenceChannel.members.each(function(member) {
  var userId = member.id;
  var userInfo = member.info;
});

members.get(userId) (Function)

The get(userId) method can be used to get a member with a specified userId.

Returns: A member object with a member.id and member.info property.

var user = presenceChannel.members.get('some_user_id');

members.me (Object)

Note: this feature was introduced in version 1.12 of the Pusher JavaScript library.

Once a user has had their subscription request authenticated (see Authenticating Users) and the subscription has succeeded (see pusher:subscription_succeeded) it is possible to access information about the local user on the presence channel.

var me = presenceChannel.members.me;

The me property represents a member object and has an id and info property. For more information on the member object see Presence channel events section.

Example

var pusher = new Pusher('app_key');
var presenceChannel = pusher.subscribe('presence-example');
presenceChannel.bind('pusher:subscription_succeeded', function() {
  var me = presenceChannel.members.me;
  var userId = me.id;
  var userInfo = me.info;
});

Events

Documentation for Presence events is only presently available for the Pusher JavaScript library. For other libraries please see the README file.

See binding to events for general information about how to bind to events on a channel object.

After a subscripting to a presence channel you can subscribe to presence events on that channel. Presence channels have a number of pre-defined events that can be bound to in order to notify a connected client about users joining or leaving the channel.

pusher:subscription_succeeded

Once a subscription has been made to a presence channel, an event is triggered with a members iterator. You could use this for example to build a user list.

Example

var channel = pusher.subscribe('presence-meeting-11');

channel.bind('pusher:subscription_succeeded', function(members) {
  // for example
  update_member_count(members.count);

  members.each(function(member) {
    // for example:
    add_member(member.id, member.info);
  });
})

The members parameter

When the pusher:subscription_succeeded event is triggered a members parameter is passed to the callback. The parameter is the channel.members property.

pusher:subscription_error

For more information on the pusher:subscription_error event please see the subscription error section of the client event docs.

pusher:member_added

The pusher:member_added event is triggered when a user joins a channel. It’s quite possible that a user can have multiple connections to the same channel (for example by having multiple browser tabs open) and in this case the events will only be triggered when the first tab is opened.

Example

channel.bind('pusher:member_added', function(member) {
  // for example:
  add_member(member.id, member.info);
});

When the event is triggered and member object is passed to the callback. The member object has the following properties:

  • id (String)
    • A unique identifier of the user. The value for this depends on the server authentication.
  • info (Object)
    • An object that can have any number of properties on it. The properties depend on the server authentication.

pusher:member_removed

The pusher:member_removed is triggered when a user leaves a channel. It’s quite possible that a user can have multiple connections to the same channel (for example by having multiple browser tabs open) and in this case the events will only be triggered when the last one is closed.

Example

channel.bind('pusher:member_removed', function(member) {
  // for example:
  remove_member(member.id, member.info);
});

When the event is triggered and member object is passed to the callback. The member object has the following properties:

  • id (String)
    • A unique identifier of the user. The value for this depends on the server authentication.
  • info (Object)
    • An object that can have any number of properties on it. The properties depend on the server authentication.

Have you tried using the search to find what you’re after? If you still have a question then get in touch with us and let us help you out.