The Pusher connection
The Pusher connection is the fundamental means of communication with the service. It is a bi-directional connection and is able to receive messages as well as emit messages from the server.
Connecting to Pusher
When you create a new Pusher object you are automatically connected to Pusher.
var pusher = new Pusher(applicationKey, options);
- applicationKey (String)
- The API 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 Pusher user dashboard.
- options (Object) [optional]
See Pusher
optionsparameter below.
Pusher options parameter
The options parameter on the Pusher constructor is an optional parameter used to apply configuration on a newly created Pusher instance.
{
encrypted: true, // true/false
auth: {
params: { // {key: value} pairs
param1: 'value1',
param2: 'value2'
},
headers: { // {key: value} pairs
header1: 'value1',
header2: 'value2'
}
}
}
The options are:
encrypted (Boolean)
Configures a Pusher instance to only connect over encrypted (SSL) connections. An application that uses SSL should use this option to ensure connection traffic is encrypted. It is also possible to force connections to use SSL by enabling the Encrypted setting within an application’s dashboard settings.
var pusher = new Pusher('app_key', { encrypted: true } );
auth (Object)
Note: this feature was introduced in version 1.12 of the Pusher JavaScript library.
The auth option lets you send additional information with the authentication request. See authenticating users.
The properties available on the auth option are as follows:
auth.params (Object)
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).
var pusher = new Pusher('app_key', {
auth: {
params: {
CSRFToken: 'some_csrf_token'
}
}
});
auth.headers (Object)
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).
var pusher = new Pusher('app_key', {
auth: {
headers: {
'X-CSRF-Token': 'some_csrf_token'
}
}
});
Detecting Connection Limits
Connection limits are currently only enforced on Sandbox plans. You will receive an email if your account exceeds your connection limit. If you are on a Sandbox plan and want to avoid connection limits upgrade your account. For more information on plan limits see pricing.
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.
var pusher = new Pusher('app_key');
pusher.connection.bind( 'error', function( err ) {
if( err.data.code === 4004 ) {
log('>>> detected limit error');
}
});
Disconnecting from Pusher
It is also possible to disconnect from Pusher.
Note: connections automatically close when a user navigates to another web page or closes their web browser so there is no need to do this manually.
pusher.disconnect();
Connection States
When working with our Pusher client library, you can monitor the state of the connection so that you can notify users about expected behaviour.
This document refers to version 1.9.0 of our library and above. Previous versions used the following events which have now been removed: pusher:connection_established and pusher:connection_failed.
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.
Available states
You can access the current state as pusher.connection.state and bind to a state change using pusher.connection.bind('connected', function() {...})
| State | Note |
|---|---|
initialized |
Initial state. No event is emitted in this state. |
connecting |
All dependencies have been loaded and Pusher 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 Pusher 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 Pusher is down, or some intermediary is blocking the connection. In this state, Pusher will automatically retry the connection every ten seconds. connecting_in events will still be triggered. |
failed |
Pusher is not supported by the browser. This implies that Flash is not available, since that is the only fallback in browsers that do not natively support WebSockets. |
disconnected |
The Pusher connection was previously connected and has now intentionally been closed. |
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.
Example state changes
Given a supported browser and functioning internet connection, the following states are expected:
initialized -> connecting -> connected
Temporary failure of the Pusher connection will cause
connected -> disconnected -> connecting -> connected
If an internet connection disappears
connected -> disconnected -> connecting -> unavailable (after ~ 30s)
When the internet connection becomes available again
unavailable -> connected
In the case that Pusher is not supported:
initialized -> failed
Binding to events
Each Pusher instance now has a connection object which manages the current state of the Pusher connection and allows binding to state changes:
var pusher = new Pusher('YOUR_API_KEY');
pusher.connection.bind('connected', function() {
$('div#status').text('Real time is go!');
});
It is also possible bind to the connecting_in event. This will give you the time until the next connection attempt.
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.")
});
Note: this isn’t a countdown, and is not fired every second.
Binding to all state changes
There’s an extra state_change utility event that fires for all state changes:
pusher.connection.bind('state_change', function(states) {
// states = {previous: 'oldState', current: 'newState'}
$('div#status').text("Pusher's current state is " + states.current);
});
Querying the connection state
var state = pusher.connection.state;