Pusher JS 1.10 released

We update the Pusher JavaScript client library fairly frequently, but in this update we’re making a few public API changes. These include: a change to the subscription error event name, the addition of a subscription succeeded event and a return value for the pusher.trigger method. So we though it warranted a blog post.

Subscription errors

If an event is triggered by either Pusher or a Pusher client library we follow the convention of prefixing the event name with pusher:. A while ago, we added an event to the Pusher JavaScript library which is triggered if an error occurs when subscribing to a channel. (More specifically, it is triggered when authenticating the subscription.) However, we forgot to prefix the event name. So, we’ve fixed this in 1.10 and updated our docs and the blog post about this.

javascript
1var pusher = new Pusher('APP_KEY');
2var channel = pusher.subscribe('private-channel');
3channel.bind('pusher:subscription_error', function(status) {
4  //  handle error
5});
Copy

Subscription success

Since you’re notified when a subscription fails it makes sense to know when a subscription succeeds. So, we’ve added an event of for that.

This is a very important update if you use client events, because this event gives you a way of knowing that you are safe to trigger client events. In earlier versions of the library, if you attempted to trigger an event on a channel before the channel subscription had registered with Pusher the event would not be published. It’s now possible to avoid this scenario by waiting for subscription confirmation before triggering the client event:

javascript
1var pusher = new Pusher('APP_KEY');
2var channel = pusher.subscribe('private-channel');
3channel.bind('pusher:subscription_succeeded', function() {
4  var triggered = channel.trigger('client-my_event', {some:'data'});
5});
Copy

There’s more information about this in the pusher:subscription_succeeded docs.

Triggering client events

We’re seeing an increasing number of requests for client events (especially useful within fast-paced HTML5 multiplayer games) and, as we’ve seen above, it’s good to know the result of any action, so we’ve updated the channel.trigger function to return a Boolean value that indicates whether or not the event was triggered successfully.

javascript
1var pusher = new Pusher('APP_KEY');
2var channel = pusher.subscribe('private-channel');
3channel.bind('pusher:subscription_succeeded', function() {
4  var triggered = channel.trigger('client-my_event', {some:'data'});
5  if(triggered) {
6    console.log("Awesome! I've sent a client event");
7  }
8});
Copy

There’s more information about this in the triggering client events docs.

Final notes

The changes to the public API hopefully maintain consistency and provide a bit more functionality which will make building realtime HTML5 apps even easier.

The new version of the Pusher JavaScript library can be found in the following locations:

• http://js.pusherapp.com/1.10/pusher.min.js (just pusher.js for non-minified version)
• https://d3ds63zw57jt09.cloudfront.net/1.10/pusher.min.js

We recommend you include the minor version (1.10) and not the patch (1.10.1) so that you benefit from automatically receiving bug fixes. We’ll won’t update a minor version with a change that affects the public API.

As always, we’ve pushed a change log and the source for the Pusher JavaScript library to github.