Connection

When you create a new Pusher object you are automatically connected to Channels.

1
var pusher = new Pusher('APP_KEY', options);

• applicationKey (String) - The application key is a string which is globally unique to your application. It can be found in the API Access section of your application within the Channels user dashboard.
• options (Object) [optional] - See Channels options parameter below.

The options parameter on the Pusher constructor is an optional parameter used to apply configuration on a newly created Pusher instance.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  cluster: 'APP_CLUSTER',
  forceTLS: true, // true/false
  auth: {
    params: { // {key: value} pairs
      param1: 'value1',
      param2: 'value2'
    },
    headers: { // {key: value} pairs
      header1: 'value1',
      header2: 'value2'
    }
  }
}

The options are:

It’s possible to define if the connection should be made over TLS. For more information see Encrypting connections

Endpoint on your server that will return the authentication signature needed for private and presence channels. Defaults to '/pusher/auth'.

For more information see authenticating users.

Defines how the authentication endpoint, defined using authEndpoint, 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 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.

For more information see the Channel authentication transport section of the authenticating users docs.

The auth option lets you send additional information with the authentication request. See authenticating users.

When creating a Pusher instance the options parameter can have an auth property set as follows:

1
2
3
4
5
6
7
var pusher = new Pusher('app_key', {
  auth: {
    params: {
      CSRFToken: 'some_csrf_token'
    }
  }
});

Additional parameters to be sent when the channel 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).

Only applied when using ajax authentication

Provides the ability to pass additional HTTP Headers to the channel authentication endpoint when authenticating a channel. This can be useful with some web application frameworks that guard against CSRF (Cross-site request forgery).

1
2
3
4
5
6
7
var pusher = new Pusher('app_key', {
  auth: {
    headers: {
      'X-CSRF-Token': 'some_csrf_token'
    }
  }
});

The identifier of the cluster your application was created in. When not supplied, will connect to the mt1 (us-east-1) cluster.

1
2
// will connect to the 'eu' cluster
var pusher = new Pusher('app_key', { cluster: 'eu' });

This parameter is mandatory when the app is created in a any cluster except mt1 (us-east-1). Read more about configuring clusters.

Disables stats collection, so that connection metrics are not submitted to Pusher's servers.

Specifies which transports should be used by Channels to establish a connection. Useful for applications running in controlled, well-behaving environments. Available transports: ws, wss, xhr_streaming, xhr_polling, sockjs. Additional transports may be added in the future and without adding them to this list, they will be disabled.

Specifies which transports must not be used by Channels to establish a connection. Useful for applications running in controlled, well-behaving environments. Available transports: ws, wss, xhr_streaming, xhr_polling, sockjs. Additional transports may be added in the future and without adding them to this list, they will be disabled.

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

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

After this time (in milliseconds) without any messages received from the server, a ping message will be sent to check if the connection is still working. Default value is is supplied by the server, low values will result in unnecessary traffic.

After sending a ping message to the server, the client waits pongTimeout milliseconds for a response before assuming the connection is dead and closing it. Default value is is supplied by the server.

1
var pusher = new Pusher('app_key', { forceTLS: true } );

When connection limits are reached additional connections over the limit will be rejected. You can capture the rejection by binding to the error event on the pusher.connection object.

1
2
3
4
5
6
var pusher = new Pusher('app_key');
pusher.connection.bind( 'error', function( err ) {
  if( err.error.data.code === 4004 ) {
    log('>>> detected limit error');
  }
});

1
pusher.disconnect();

There are multiple ways to use the connection state API:

• Bind to individual state change events
• Bind to all state change events
• Query the state directly

Additionally, the reconnect mechanism is now more transparent. This means that you can display messages that tell the user when the service might be connected.

You can access the current state as pusher.connection.state and bind to a state change using pusher.connection.bind('connected', function() {...})

Additionally a connecting_in event is periodically emitted whilst the connection is in the connecting or unavailable state. This event indicates the time in seconds before another connection attempt is made.

Given a supported browser and functioning internet connection, the following states are expected:

1
initialized -> connecting -> connected

Temporary failure of the Channels connection will cause

1
connected -> connecting -> connected

If an internet connection disappears

1
connected -> connecting -> unavailable (after ~ 30s)

When the internet connection becomes available again

1
unavailable -> connected

In the case that Channels is not supported:

1
initialized -> failed

Each Channels instance now has a connection object which manages the current state of the Channels connection and allows binding to state changes:

1
2
3
4
5
var pusher = new Pusher('_APP_KEY');

pusher.connection.bind('connected', function() {
  $('div#status').text('Realtime is go!');
});

It is also possible bind to the connecting_in event. This will give you the time until the next connection attempt.

1
2
3
4
pusher.connection.bind('connecting_in', function(delay) {
  alert("I haven't been able to establish a connection for this feature.  " +
  "I will try again in " + delay + " seconds.")
});

There's an extra state_change utility event that fires for all state changes:

1
2
3
4
pusher.connection.bind('state_change', function(states) {
  // states = {previous: 'oldState', current: 'newState'}
  $('div#status').text("Channels current state is " + states.current);
});

1
var state = pusher.connection.state;