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.

Presence channels have some limits associated with them: 100 members maximum, 1KB limit for user object, and maximum 128 characters for user id. If you use a numeric user id, remember that the maximum size integer that is representable in JavaScript is 2^53.

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.

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.

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.

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.

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.