Channels vs events

We’ve moved all the docs to this page. One thing I think we need to clarify however is the difference between channels and events. Muddling the purpose of either can lead to a lot of confusion. The following is a high level summary of their respective purposes:

Channels:

• are used to grant permissions to a group of users who can access certain events
• are used to filter similar events
• can be seen as a namespace for grouping events

Events:

• describe an action that has occurred in your system
• are tied into the logic and entities that exist in your app
• should be named in a systematic way that reflects your app’s domain

What does this mean?

Let’s look at some examples of how these can be used.

What channel names to use?

Our first port of call is to think about what permissions we might need in our application.

If we have multiple accounts or projects where permission is needed to view them, it might make sense to use these as channel names.

pusher.subscribe("account-"); pusher.subscribe("project-");

If our application has entities that change frequently (such as pages on a wiki), we may want to use an individual document as a channel name.

pusher.subscribe("page-");

If we want to filter the information coming in we may want to use a channel for that - eg, I could have a channel called "maxthelion" that showed my tweets.

pusher.subscribe("tweets-");

You can, of course, have a single channel for your entire app if it is simple enough:

pusher.subscribe("some-random-channel-name");

However, it usually pays to think a little about what you may need in future.

What event names to use?

It is generally a good idea to think of event names as a description of something that has occurred in your app.

Events often mirror methods in our existing API, but are a notification that they have occurred. In the same way that we strive for descriptive names for our methods, we should try and make our event names descriptive too.

Therefore, if I have a function, ‘create’, that creates a new ‘todo’, I may want to call my corresponding event something similar.

myChannel.bind("create", function(){ /* do something */ });

While a function name describes something you want to invoke, events describe something that has already happened. It can therefore be helpful conceptually to actually use the past tense in your event names:

myChannel.bind("created", function(){ /* do something */ });

This is not a convention we tend to use in our examples, but does illustrate the point.

Namespacing within events

While you may have several entities that have similar methods, you may want use the name of the class in the event as well.

MyClass.create()

on your server can therefore trigger the event `MyClass-create’ that will be sent out to the connected clients.

In most applications, you will have basic CRUD operations associated with any given entity, and will often end up with events such as this:

myChannel.bind("Todo-create" function(){ /* add it into ui / }); myChannel.bind("Todo-update" function(){ / change it in ui / }); myChannel.bind("Todo-delete" function(){ / remove it from ui */ });

Remember that the names of your events are going to make the intentions of your javascript code more clear. While verbose, the following describes what has happened:

myChannel.bind("new-datapoint-for-graph", function(data){ myGraph.addDataPoint(data); });

Whereas, this will not really help you very much:

myChannel.bind('data', function(data){ myGraph.addDataPoint(data); });

Conclusion

Pusher channels and events allow you a lot of flexibility when designing your applications, but it can often be a bit daunting knowing what to call them.

Hopefully this demonstrates some of the ways that you can do this, and that following a few simple rules can help you out.

Cheers!

P.s. Have you built realtime apps with Pusher? If not, go on, create a free Pusher account and let us know what you think!