Pusher

Documentation

Getting started
How it works
Quick start
Debugging your apps
How do I...?
Using Pusher
Client API Overview
Publisher API Overview
Authenticating Users
WebHooks
Libraries
Publisher Libraries
Client Libraries
Reference
Authentication Signatures
Pusher JS changelog
Flash Fallback
Browser compatibility
REST API reference
Pusher WebSocket Protocol
Resources
Other resources on the web
From the blog
Channels vs Events
Showing who's online-(PHP)
Introducing private channels
Backbone.js, now realtime with Pusher

Channels

Channels are a fundamental concept in Pusher. Each application has a number of channels, and every client can choose which channels it connects to.

Channels provide:

  • A way of filtering data. For example, in a chat application there may be a channel for people who want to discuss 'dogs'
  • A way of controlling access to different streams of information. For example, a project management application would want to authorise people to get updates about 'secret-projectX'

We strongly recommend that channels are used to filter your data and that it is not achieved using events. This is because all events published to a channel are sent to all subscribers, regardless of their event binding.

Channels don't need to be explicitly created, and are instantiated on client demand. This means that creating a channel is easy. Just tell a client to subscribe to it.

Channel Types & Naming Conventions

Channel names should only include lower and uppercase letters, numbers and the following punctuation _ - = @ , . ;

As an example this is a valid channel name:

foo-bar_1234@=,.;

There are 3 types of channels at the moment:

  • Public channels can be subscribed to by anyone who knows their name
  • Private channels should have a private- prefix. They allow you to control access to the data you are broadcasting
  • Presence channels should have a presence- prefix. They let you 'register' user information on subscription, and let other members of the channel know who's online

Public channels

You can subscribe and unsubscribe from channels at any time. There's no need to wait for the Pusher to finish connecting first.

Subscribe

var channel = pusher.subscribe(channelName);
  • channelName (String)
    • The name of the channel to subscribe to.
  • Returns
    • A Channel object which events can be bound to. See binding to events for more information on the Channel object.

Unsubscribe

pusher.unsubscribe(channelName);
  • channelName (String)
    • The name of the channel to unsubscribe from.

Events

You can bind to the following pusher: events on a public channel:

Private channels

Private channels should be used when access to the channel needs to be restricted in some way. In order for a user to subscribe to a private channel permission must be authorised. The authentication occurs via a HTTP Request to a configurable authentication url when the subscribe method is called with a private- channel name. In the JavaScript client library the HTTP Request is executed via AJAX (see Authenticating Users).

Private channels must be prefixed with `private-`. See channel naming conventions.

Private channel subscriptions must be authenticated. See Authenticating Users.

Subscribe

var privateChannel = pusher.subscribe(privateChannelName);
  • privateChannelName (String)
    • The name of the channel to subscribe to. Since it is a private channel the name must be prefixed with 'private-'
  • Returns
    • A Channel object which events can be bound to. See binding to events for more information on the Channel object.

Unsubscribe

pusher.unsubscribe(privateChannelName);
  • privateChannelName (String)
    • The name of the channel to unsubscribe from.

Events

You can bind to the following pusher: events on a private channel:

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 HTTP Request response 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.

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

Presence channel subscriptions must be authenticated. See Authenticating Users.

Subscribe

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
    • A Channel object which events can be bound to. See binding to events for more information on the Channel object.

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.

Unsubscribe

pusher.unsubscribe(presenceChannelName);
  • presenceChannelName (String)
    • The name of the channel to unsubscribe from.

Events

After a subscripting to a presence channel you can subscribe to presence events on that channel. See the Presence channel events section for more information.

Presence Demo

For a demo see our Pusher presence demo (source).

Accessing channels

If a channel has been subscribed to already it is possible to access channels by name, through the pusher.channel function:

var channel = pusher.channel(channelName);
  • channelName (String)
    • The name of the channel to retrieve