authTransport (String)

Defines how the authentication endpoint, defined using authEndpoint, will be called. There are two options available: ajax and jsonp.

ajax - The default option where an XMLHttpRequest object will be used to make a request. The parameters will be passed as POST parameters.

jsonp - The authentication endpoint will be called by a <script> tag being dynamically created pointing to the endpoint defined by authEndpoint. This can be used when the authentication endpoint is on a different domain to the web application. The endpoint will therefore be requested as a GET and parameters passed in the query string.

CSRF

If you require a CSRF header for incoming requests to the private channel authentication endpoint on your server, you should add a CSRF token to the auth hash under headers. This is applicable to frameworks which apply CSRF protection by default.

disableStats (Boolean)

Disables stats collection, so that connection metrics are not submitted to Pusher’s servers. These stats are used for internal monitoring only and they do not affect the account stats.

enabledTransports (Array)

Specifies which transports should be used by Pusher to establish a connection. Useful for applications running in controlled, well-behaving environments. Available transports for web: ws, wss, xhr_streaming, xhr_polling, sockjs. If you specify your transports in this way, you may miss out on new transports we add in the future.

disabledTransports (Array)

Specifies which transports must not be used by Pusher to establish a connection. This settings overwrites transports whitelisted via the enabledTransports options. Available transports for web: ws, wss, xhr_streaming, xhr_polling, sockjs. This is a whitelist, so any new transports we introduce in the future will be used until you explicitly add them to this list.

wsHost, wsPort, wssPort, httpHost, httpPort, httpsPort

These can be changed to point to alternative Pusher URLs (used internally for our staging server).

wsPath

Useful in special scenarios if you're using the library against an endpoint you control yourself. This is used internally for testing.

ignoreNullOrigin (Boolean)

Ignores null origin checks for HTTP fallbacks. Use with care, it should be disabled only if necessary (i.e. PhoneGap).

activityTimeout (Integer)

If there is no activity for this length of time (in milliseconds), the client will ping the server to check if the connection is still working. The default value is set by the server. Setting this value to be too low will result in unnecessary traffic.

pongTimeout (Integer)

Time before the connection is terminated after a ping is sent to the server. Default is 30000 (30s). Low values will cause false disconnections, if latency is high.

Global configuration

Pusher.logToConsole (Boolean)

Enables logging to the browser console via calls to console.log.

Pusher.log (Function)

Assign a custom log handler for the Pusher library logging. For example:

Pusher.log= (msg) => {
console.log(msg);
};

By setting the log property you also override the use of Pusher.enableLogging.

Connection

A connection to Pusher is established by providing your APP_KEY and APP_CLUSTER to the constructor function:

constsocket=newPusher(APP_KEY, {
cluster:APP_CLUSTER,
});

This returns a socket object which can then be used to subscribe to channels.

One reason this connection might fail is your account being over its' limits. You can detect this in the client by binding to the error event on the pusher.connection object. For example:

Connection States

All dependencies have been loaded and Channels is trying to connect. The connection will also enter this state when it is trying to reconnect after a connection failure.

connected

The connection to Channels is open and authenticated with your app.

unavailable

The connection is temporarily unavailable. In most cases this means that there is no internet connection. It could also mean that Channels is down

failed

Channels is not supported by the browser. This implies that WebSockets are not natively available and an HTTP-based transport could not be found.

disconnected

The Channels connection was previously connected and has now intentionally been closed.

Socket IDs

Making a connection provides the client with a new socket_id that is assigned by the server. This can be used to distinguish the client's own events. A change of state might otherwise be duplicated in the client. More information on this pattern is available here.

It is also stored within the socket, and used as a token for generating signatures for private channels.

Subscribing to channels

Public channels

The default method for subscribing to a channel involves invoking the subscribe method of your socket object:

constchannel=socket.subscribe('my-channel');

This returns a Channel object which events can be bound to.

Private channels

Private channels are created in exactly the same way as normal channels, except that they reside in the 'private-' namespace. This means prefixing the channel name:

constchannel=socket.subscribe('private-my-channel');

Encrypted Channels (BETA)

Like private channels, encrypted channels have their own namespace, 'private-encrypted-'. For more information about encrypted channels, please see the docs.

Please note that encrypted channels are only officially supported for our 'web' and 'node' clients for now. We know for sure this won't work in React Native builds since the React Native runtime does not include the required crypto functionality we depend on. Please let us know if you need this functionality in our web-worker or React Native builds!

constchannel=socket.subscribe('private-encrypted-my-channel');

It is possible to access channels by name, through the channel function:

constchannel=socket.channel('private-my-channel');

It is possible to access all subscribed channels through the allChannels function:

socket.allChannels().forEach(channel=>console.log(channel.name));

Private, presence and encrypted channels will make a request to your authEndpoint (/pusher/auth) by default, where you will have to authenticate the subscription. You will have to send back the correct auth response and a 200 status code.

Unsubscribing from channels

To unsubscribe from a channel, invoke the unsubscribe method of your socket object:

socket.unsubscribe('my-channel');

Unsubscribing from private channels is done in exactly the same way, just with the additional private- prefix:

socket.unsubscribe('private-my-channel');

Binding to events

Event binding takes a very similar form to the way events are handled in jQuery. You can use the following methods either on a channel object, to bind to events on a particular channel; or on the pusher object, to bind to events on all subscribed channels simultaneously.

bind and unbind

Binding to "new-message" on channel: The following logs message data to the console when "new-message" is received

Unsubscribe behaviour varies depending on which parameters you provide it with. For example:

// Remove just `handler` for the `new-comment` eventchannel.unbind('new-comment', handler);
// Remove all handlers for the `new-comment` eventchannel.unbind('new-comment');
// Remove `handler` for all eventschannel.unbind(null, handler);
// Remove all handlers for `context`channel.unbind(null, null, context);
// Remove all handlers on `channel`channel.unbind();

bind_global and unbind_global

bind_global and unbind_global work much like bind and unbind, but instead of only firing callbacks on a specific event, they fire callbacks on any event, and provide that event along to the handler along with the event data. For example:

unbind_all

The unbind_all method is equivalent to calling unbind() and unbind_global() together; it removes all bindings, global and event specific.

Batching auth requests (aka multi-auth)

Currently, pusher-js itself does not support authenticating multiple channels in one HTTP request. However, thanks to @dirkbonhomme you can use the pusher-js-auth plugin that buffers subscription requests and sends auth requests to your endpoint in batches.

Default events

There are a number of events which are used internally, but can also be of use elsewhere, for instance subscribe. There is also a state_change event - which fires whenever there is a state change. You can use it like this:

Connection Events

To listen for when you connect to Pusher:

socket.connection.bind('connected', callback);

And to bind to disconnections:

socket.connection.bind('disconnected', callback);

Self-serving JS files

You can host JavaScript files yourself, but it's a bit more complicated than putting them somewhere and just linking pusher.js in the source of your website. Because pusher-js loads fallback files dynamically, the dependency loader must be configured correctly or it will be using js.pusher.com.

In the dist/web folder, you should see the files you need: pusher.js, pusher.min.js, json2.js, json.min.js, sockjs.js and sockjs.min.js. pusher.js should be built referencing your URLs as the dependency hosts.

First, make sure you expose all files from the dist directory. They need to be in a directory with named after the version number. For example, if you're hosting version 4.2.0 under http://example.com/pusher-js (and https for SSL), files should be accessible under following URL's:

SockJS compatibility

Most browsers have a limit of 6 simultaneous connections to a single domain, but Internet Explorer 6 and 7 have a limit of just 2. This means that you can only use a single Pusher connection in these browsers, because SockJS requires an HTTP connection for incoming data and another one for sending. Opening the second connection will break the first one as the client won't be able to respond to ping messages and get disconnected eventually.

All other browsers work fine with two or three connections.

Developing

You can optionally pass a PORT environment variable to run the server on a different port. You can also pass CDN_HTTP and CDN_HTTPS variables if you wish the library to load dependencies from a new host.

This command will serve pusher.js, sockjs.js, json2.js, and their respective minified versions.

Core Vs. Platform-Specific Code

New to PusherJS 3.1 is the ability for the library to produce builds for different runtimes: classic web, React Native, NodeJS and
Web Workers.

In order for this to happen, we have split the library into two directories: core/ and runtimes/. In core we keep anything that is platform-independent. In runtimes we keep code that depends on certain runtimes.

Throughout the core/ directory you'll find this line:

importRuntimefrom"runtime";

We use webpack module resolution to make the library look for different versions of this module depending on the build.

For web it will look for src/runtimes/web/runtime.ts. For ReactNative, src/runtimes/react-native/runtime.ts. For Node: src/runtimes/node/runtime.ts. For worker: src/runtimes/worker/runtime.ts.

Each of these runtime files exports an object (conforming to the interface you can see in src/runtimes/interface.ts) that abstracts away everything platform-specific. The core library pulls this object in without any knowledge of how it implements it. This means web build can use the DOM underneath, the ReactNative build can use its native NetInfo API, Workers can use fetch and so on.

Building

In order to build SockJS, you must first initialize and update the Git submodule:

git submodule init
git submodule update

Then simply run:

make web

This will build the source files relevant for the web build into dist/web.

In order to specify the library version, you can either update package.json or pass a VERSION environment variable upon building.

Other build commands include:

make react-native # for the React Native build
make node # for the NodeJS build
make worker # for the worker build

Testing

Each test environment contains two types of tests:

unit tests,

integration tests.

Unit tests are simple, fast and don't need any external dependencies. Integration tests usually connect to production and js-integration-api servers and can use a local server for loading JS files, so they need an Internet connection to work.

There are 3 different testing environments: one for web, one for NodeJS and one for workers. We may consider adding another one for React Native in the future.

The web and worker tests use Karma to execute specs in real browsers. The NodeJS tests use jasmine-node.

To run the tests:

# For web
make web_unit
make web_integration
# For NodeJS
make node_unit
make node_integration
# For workers
make worker_unit
make worker_integration

If you want your Karma tests to automatically reload, then in spec/karma/config.common.js set singleRun to false.