Pusher Channels Javascript Client

This Pusher Channels client library supports web browsers, web workers and Node.js

If you're looking for the Pusher Channels server library for Node.js, use pusher-http-node instead.

For tutorials and more in-depth information about Pusher Channels, visit our official docs.

For reporting issues, bugs, and feature requests, please feel free to open a pull request or open an issue. If you do not receive a timely response, feel free to check our support portal.

Usage Overview

The following topics are covered:

• Installation
• Web
• React Native
• Web Workers
• Node.js
• Initialization
• Configuration
• Global Configuration
• Connection
• Socket IDs
• Subscribing to Channels (Public and Private)
• Accessing Channels
• Binding to Events
• Default events
• Developing
• Core vs. Platform-specific Code
• Building
• Testing

Supported platforms

• Web

• We test against Chrome, Firefox and Safari.

• Works in web pages, web workers and service workers

• Works with all major web frameworks, including

  • Angular (See Angular tutorial)
  • React (See React tutorial)
  • Vue.js (see Vue.js tutorial)

• React Native

• Node.js

Installation

Web

If you're using Pusher Channels on a web page, you can install the library via:

Encrypted Channel Support

The encryption primitives required to power encrypted channels increase the bundle size quite significantly. In order to keep bundle sizes down, the default web and worker builds of pusher-js no longer support encrypted channels.

If you'd like to make use of encrypted-channels, you need to import the with-encryption builds as described below.

Yarn (or NPM)

You can use any NPM-compatible package manager, including NPM itself and Yarn.

yarn add pusher-js

Then:

import Pusher from 'pusher-js';

If you'd like to use encrypted channels:

import Pusher from 'pusher-js/with-encryption';

Or, if you're not using ES6 modules:

const Pusher = require('pusher-js');

If you'd like to use encrypted channels:

const Pusher = require('pusher-js/with-encryption');

CDN

<script src="https://js.pusher.com/7.0/pusher.min.js"></script>

If you'd like to use encrypted channels:

<script src="https://js.pusher.com/7.0/pusher-with-encryption.min.js"></script>

You can also use cdnjs.com if you prefer or as a fallback.

Bower (discouraged)

Or via Bower:

bower install pusher

and then:

<script src="https://github.com/pusher/pusher-js/raw/v8.5.0/bower_components/pusher/dist/web/pusher.min.js"></script>

Typescript

We've provided typescript declarations since v5.1.0. Most things should work out of the box but if you need access to specific types you can import them like so:

import Pusher from 'pusher-js';
import * as PusherTypes from 'pusher-js';

var presenceChannel: PusherTypes.PresenceChannel;
...

React Native

⚠️ Important notice

React Native support has been deprecated and soon will be removed from this repository.

Please, use our official React Native SDK instead.

Web Workers

(pusher-js's Web Workers implementation is currently not compatible with Internet Explorer) You can import the worker script (pusher.worker.js, not pusher.js) from the CDN:

importScripts('https://js.pusher.com/7.0/pusher.worker.min.js');

If you'd like to use encrypted channels:

importScripts('https://js.pusher.com/7.0/pusher-with-encryption.worker.min.js');

If you're building your worker with a bundler, you can import the worker entrypoint

import Pusher from 'pusher-js/worker'

If you'd like to use encrypted channels:

import Pusher from 'pusher-js/worker/with-encryption'

Node.js

Having installed pusher-js via an NPM-compatible package manager, run:

import Pusher from 'pusher-js';

Notes:

• For standard WebWorkers, this build will use HTTP as a fallback.
• For ServiceWorkers, as the XMLHttpRequest API is unavailable, there is currently no support for HTTP fallbacks. However, we are open to requests for fallbacks using fetch if there is demand.

Initialization

const pusher = new Pusher(APP_KEY, {
  cluster: APP_CLUSTER,
});

You can get your APP_KEY and APP_CLUSTER from the Pusher Channels dashboard.

Configuration

There are a number of configuration parameters which can be set for the client, which can be passed as an object to the Pusher constructor, i.e.:

const pusher = new Pusher(APP_KEY, {
  cluster: APP_CLUSTER,
  channelAuthorization: {
    endpoint: 'http://example.com/pusher/auth'
  },
});

For most users, there is little need to change these. See client API guide for more details.

forceTLS (Boolean)

Forces the connection to use TLS. When set to false the library will attempt non-TLS connections first. Defaults to true.

userAuthentication (Object)

Object containing the configuration for user authentication. Valid keys are:

• endpoint (String) - Endpoint on your server that will return the authentication signature needed for signing the user in. Defaults to /pusher/user-auth.

• transport (String) - Defines how the authentication endpoint will be called. There are two options available:

• 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 userAuthentication.endpoint. 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.

• params (Object) - Additional parameters to be sent when the user authentication endpoint is called. When using ajax authentication the parameters are passed as additional POST parameters. When using jsonp authentication the parameters are passed as GET parameters. This can be useful with web application frameworks that guard against CSRF (Cross-site request forgery).

• headers (Object) - Only applied when using ajax as authentication transport. Provides the ability to pass additional HTTP Headers to the user authentication endpoint. This can be useful with some web application frameworks that guard against CSRF CSRF (Cross-site request forgery).

• paramsProvider (Function) - When present, this function is called to get additional parameters to be sent when the user authentication endpoint is called. This is equivalent to passing them on the params key, but allows for the parameters to be retrieved dynamically at the time of the request.

• headersProvider (Function) - When present, this function is called to get additional headers to be sent when the user authentication endpoint is called. This is equivalent to passing them on the headers key, but allows for the headers to be retrieved dynamically at the time of the request.

• customHandler (Function) - When present, this function is called instead of a request being made to the endpoint specified by userAuthentication.endpoint.

For more information see authenticating users.

channelAuthorization (Object)

Object containing the configuration for user authorization. Valid keys are:

• endpoint (String) - Endpoint on your server that will return the authorization signature needed for private and presence channels. Defaults to /pusher/auth.

• transport (String) - Defines how the authorization endpoint will be called. There are two options available:

• 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 authorization endpoint will be called by a <script> tag being dynamically created pointing to the endpoint defined by channelAuthorization.endpoint. This can be used when the authorization 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.

• params (Object) - Additional parameters to be sent when the channel authorization endpoint is called. When using ajax authorization the parameters are passed as additional POST parameters. When using jsonp authorization the parameters are passed as GET parameters. This can be useful with web application frameworks that guard against CSRF (Cross-site request forgery).

• headers (Object) - Only applied when using ajax as authorizing transport. Provides the ability to pass additional HTTP Headers to the user authorization endpoint. This can be useful with some web application frameworks that guard against CSRF CSRF (Cross-site request forgery).

• paramsProvider (Function) - When present, this function is called to get additional parameters to be sent when the user authentication endpoint is called. This is equivalent to passing them on the params key, but allows for the parameters to be retrieved dynamically at the time of the request.

• headersProvider (Function) - When present, this function is called to get additional headers to be sent when the user authentication endpoint is called. This is equivalent to passing them on the headers key, but allows for the headers to be retrieved dynamically at the time of the request.

• customHandler (Function) - When present, this function is called instead of a request being made to the endpoint specified by channelAuthorization.endpoint.

For more information see authorizing users.

cluster (String)

Specifies the cluster that pusher-js should connect to. If you'd like to see a full list of our clusters, click here. If you do not specify a cluster, mt1 will be used by default.

const pusher = new Pusher(APP_KEY, {
  cluster: APP_CLUSTER,
});

disableStats (deprecated) (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. This option is deprecated since stats collection is now disabled by default

enableStats (Boolean)

Enables stats collection, so that connection metrics are submitted to Pusher’s servers. These stats can help pusher engineers debug connection issues.

enabledTransports (Array)

Specifies which transports should be used by pusher-js 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.

// Only use WebSockets
const pusher = new Pusher(APP_KEY, {
  cluster: APP_CLUSTER,
  enabledTransports: ['ws']
});

Note: if you intend to use secure websockets, or wss, you can not simply specify wss in enabledTransports, you must specify ws in enabledTransports as well as set the forceTLS option to true.

// Only use secure WebSockets
const pusher = new Pusher(APP_KEY, {
  cluster: APP_CLUSTER,
  enabledTransports: ['ws'],
  forceTLS: true
});

disabledTransports (Array)

Specifies which transports must not be used by pusher-js 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.

```js // Use all transports except for sockjs const pusher = new Pusher(APP_KEY, { cluster: APP_CLUSTER, disabledTransports: ['sockjs'] });

// Only use WebSockets const pusher = new Pusher(APP_K